VAX DOCUMENT 
User Manual, Volume 1 


Order Number: AA-—JT84A-TE 


This manual describes the VAX DOCUMENT product for the new user. 
It includes a full description of the doctype-independent tags used in all 
types of VAX DOCUMENT documents... 


Revision/Update Information: — This is a new manual. 
Operating System and Version: VMS Version 4.4 or higher 
MicroVMS Version 4.4 or higher 


Software Version: VAX DOCUMENT Version 1.0 


digital equipment corporation maynard, massachusetts 


July 1987 


The information in this document is subject to change without notice and should 
not be construed as a commitment by Digital Equipment Corporation. Digital 
Equipment Corporation assumes no responsibility for any errors that may appear 
in this document. 


The software described in this document is furnished under a license and may be 
used or copied only in accordance with the terms of such license. 


No responsibility is assumed for the use or reliability of software on equipment 
that is not supplied by Digital Equipment Corporation or its affiliated companies. 


Copyright ©1987 by Digital Equipment Corporation 


All Rights Reserved. 
Printed in U.S.A. 


The postpaid READER’S COMMENTS form on the last page of this document 
requests the user’s critical evaluation to assist in preparing future documentation. — 


The following are trademarks of Digital Equipment Corporation: 


DEC DIBOL UNIBUS 
DEC/CMS EduSystem VAX 
DEC/MMS IAS VAXcluster 
DECnet MASSBUS VMS 
DECsystem—10 PDP VT 
DECSYSTEM-20 PDT 

DECUS RSTS 


DECwriter RSX CIES GEL es 


ZK4458 


This document was prepared using VAX DOCUMENT, Version 1.0 


Contents 











PREFACE XV 

CHAPTER 1 INTRODUCTION TO VAX DOCUMENT 1-1 

1.1 THE VAX DOCUMENT DOCUMENTATION SET 1-1 
1.2 FEATURES OF VAX DOCUMENT 1-2 
1.3 USING A GENERIC MARKUP LANGUAGE 1-3 
1.4 INTRODUCTION TO THE DOCUMENT COMMAND LINE 1-4 
1.5 TYPES OF DOCUMENTS 1-4 
1.6 OVERVIEW OF THE VAX DOCUMENT SYSTEM 1-6 
1.6.1 How VAX DOCUMENT Processes a File —- —-——E 1-6. 

1.6.2 Informational Messages _——SsSCOessSSSSS—CssFSSS 1-7 

1.6.3  Doctype-Independent and Doctype-Specific Tags 1-8 

1.6.4 Context-Sensitive Tags _.---—SssSOesS—C—CsSSSSS—C—FSS 1-9 

1.7 PROCESSING BOOKS AND ELEMENTS OF BOOKS 1-9 

CHAPTER 2 CREATING AN SDML FILE 2-1 
2.1 GLOBAL TAGS . 2-1 
2.1.1 Tag Arguments _ —SS—S—OeFesFsSSSSSSSSSSFeFeFsFsSSSSSSSS 2-2 

2.2 CODING AN SDML FILE 2-2 
2.3 CODING CONSIDERATIONS 2-3 
2.3.1 Coding Text that Looks Like a Tag SS ssS 2-3 

2.3.2 Coding Opening and Closing Parentheses in an 

Argument _—ssssSsSsSsSFeFeFFSSSSSSSSSSSsFeFeeFesFsSSSSSSSSSSsSssSSSFS 2-4 


2.3.3 Coding a Backslash in an Argument —— SS 2—5 


Contents 


2.3.4 Coding a Vertical Bar or Ampersand inan Argument __ 2-5 

2.3.5 Coding a Hyphen in Text —-- —ss—CSCSssSSSSSSSS 2-6 

a SL aR a IY ce, Ce ea La OE EIN, ET AA ON} 
CHAPTER 3 USING COMMON TAGS 3-1 
3.1 PARAGRAPHS 3-1 

3.2. HEADINGS 3-2 

3.3 CHAPTERS 3-2 

3.4 FRONT MATTER 3-3 

3.4.1 Title Page _————SsSSSSSSSSFSFSSSSSSSSSSSSSSSSS 3-3 

3.4.2 Copyright Page _ SS —esssSS—S—C—OFeFessSSSSSS—S—COFeFFFSSSSS—COFFSSSSS 3-4 

3.4.3 Preface — 3-4 

3.5 BACK MATTER 3-4 

3.5.1 Appendixes — SS SSSSSSSSSS—SsFFSFSSSSSSSSSSSSSSSSSSSSSseeFFeFssS 3-5 

3.5.2 Glossary _——- ————SFssSSSSSSSSSFSFSSSSSSSSSSSSSSSSSSeeeeFeSSSSSSSSSSSSSSSSSS 3-5 

3.6 LISTS 3-5 

3.7. TABLES | 3-6 

3.7.1. Controlling Table Attributes ... SESS 3-10 


3.7.1.1 Controlling a Table’s Margins * 3—10 
3.7.1.2 Controlling Page Breaks in Tables ¢ 3-12 


3.8 FIGURES 3-14 
3.8.1 Figure Elements = —SSESEESSSSSSSSSS—SSFSSSSSSSSSSSSSS—SSSS 3-15 
3.8.2 Controlling Figure Attributes .— SESS 3-16 
3.8.2.1 Controlling a Figure’s Margins ¢ 3—16 
3.8.2.2 | Controlling Page Breaks in Figures * 3-17 
3.8.3 Including Graphics Files ——--_—SSESEEESSS—CSFSF 3-18 


3.9 EXAMPLES 3-19 
3.9.1. Informal Examples SS sssSSSSSSFFSSSSSSSSS—CFFSSSSSSSSSSSSSSSS— 3-19 
3.9.2 Formal Examples _ ——EESSSSSSSSSSSSS——eFeFeFFssssSsSsSSFsssSSSS 3-20 


Contents 














CHAPTER 4 PROCESSING AND PRINTING FILES AND BOOKS 4-1 
4.1 THE FOUR TYPES OF PROCESSES 4-1 
4.2 CHAIN OF PROCESSING 4-2 
4.3 PROCESSING INDIVIDUAL FILES 4-2 
4.4 CONTROLLING FILE PROCESSING 4-3 

4.4.1. Keeping Intermediate Files (Using /KEEP) 4-4 
4.4.2 Processing in Batch Mode (Using /BATCH) 4—5 
4.4.3 Printing an Existing File 4-5 
4.4.4 Reprocessing a File for a Different Destination 4-6 
4.4.5 Processing or Reprocessing Selected Pages (Using 
/DEVICE_CONVERTER) 4-6 
4.4.6 Altering Page Parameters (Using /DEVICE) 4-7 
4.4.7. Including Additional Files (Using /INCLUDE) 4-7 
4.4.8 Conditionalizing Files (Using /CONDITION) 4-7 
4.4.8.1 Using the <SET_CONDITION> Tag * 4-8 
4.4.8.2 Setting More than One Condition * 4—8 
4.4.9 Assigning a New Output File Name 4-8 
4.5 BOOKBUILDING 4-9 
4.5.1 Creating Input Files 4-9 
4.5.2 Creating a Profile 4-10 
4.5.3. Processing a Profile 4—11 
4.5.3.1 Listing the Input Files ¢ 4—11 
4.5.3.2 Defining Logical Names for Included Files * 4—12 
4.5.4 Recovering from Errors 4-13 
4.6 PROCESSING AN ELEMENT OF A BOOK 4-13 
4.6.1 Building a Conditionalized Book Element 4-14 
4.7 PROCESSING A SUBELEMENT OF A BOOK 4-14 
4.8 SIMULTANEOUS ELEMENT AND BOOKBUILDS 4-15 


< 


Contents 








CHAPTER 5 TROUBLESHOOTING SDML FILES 5-1 

5.1 ERROR MESSAGES 5-1 

5.2 OUTPUT PROBLEMS 5-3 

5.2.1. Incorrect Paragraph Indentation — SESS 5-3 

5.2.2 Problems with Examples —-  ——SssSSSSSSSSSFFSFSSSSS 5-3 

5.2.3. Incorrect Sequencing of Formal Elements 5-4 

CHAPTER 6 REFERENCING SYMBOL-NAMES 6-1 
6.1. CREATING SYMBOL-NAMES 6-1 

6.2 STORING SYMBOL-NAMES IN A CROSS-REFERENCE FILE 6-2 

6.3 CREATING SYMBOL-NAMES FOR TEXT AND BOOK ELEMENTS 6-2 

6.4 REFERENCING TEXT AND BOOK ELEMENT SYMBOL-NAMES 6-4 

6.4.1 Controlling the Output of a Reference ————sS—CSs 6-4 

6.4.2 Referencing Symbol-Names in Other Files ————__ 6-6 

6.5 CREATING A PRELIMINARY PROFILE 6-6 

6.6 ADDING NEW SYMBOL-NAMES 6-7 





CHAPTER 7 GENERATING A TABLE OF CONTENTS, INDEX, AND 


vi 


MASTER INDEX 7-1 
CREATING A TABLE OF CONTENTS 7-1 
CREATING AN INDEX : 7-2 


7.2.1. Creating Main Index Entries .— ——S<C 7-4 


Ye ay 


1 

2 Using the BOLD Attribute * 7—6 

3 Using the ITALIC Attribute « 7-6 

4 Using the MASTER Attribute ¢ 7-6 

5 Using the <XAPPEND> Attribute e 7—7 
7.2.2.6 | Using the <xSORT> Attribute * 7—7 

7.2.3 Creating Cross-Reference Index Entries 

7.2.4 Processing an Index 

7.2.5 Using Indexing Options 


Contents 


Using the BEGIN and END Attributes « 7—5 


7.2.5.7 | Using the GUIDE_HEADINGS and NOGUIDE_HEADINGS 


Keywords ¢ 7-10 


7.2.5.8 | Using the OVERRIDE_MASTER and NOOVERRIDE_MASTER 


Keywords ¢ 7-10 
7.2.5.9 Using the SORT Keyword ¢ 7—10 





7.3 CREATING A MASTER INDEX 7-11 
7.3.1 Creating Intermediate Index Files 7-11 

7.3.2 Creating the Master Index Data File 7-11 

7.3.3 Creating the Master Index File 7-12 
CHAPTER 8 SPECIAL FEATURES 8-1 
8.1 PROVIDING EMPHASIS 8-1 
8.2 USING FOOTNOTES 8-3 
33 USING CALLOUTS 8-4 
8.4 DRAWING LARGE BRACES AND BRACKETS 8-5 
8.5 CONTROLLING CASE 8-6 
8.6 PROVIDING QUOTATION MARKS 8-6 
8.7 PLACING PARENTHESES AROUND A SINGLE CHARACTER 8-7 
8.8 DRAWING HORIZONTAL AND VERTICAL ELLIPSES 8-7 
8.9 SHOWING SPECIAL CHARACTERS 8-8 


vii 


Contents 


8.10 


USING FORMATTING TAGS 


8.10.1 Specifying Page Breaks 


8.10.2 Specifying Line Breaks 


8.10.3 Keeping Text on a Single Line 


8.10.4 Controlling Page and Line Breaks for Final Production — 





CHAPTER9 DOCTYPE-INDEPENDENT TAG DESCRIPTIONS 


viii 


<ABSTRACT> 
<ACCENT> | 
<ALIGN_AFTER> 
<ALIGN_CHAR> 
<ALIGN_NUMBER> 
<AMPERSAND> 
<APPENDIX> 
<BACKSLASH> 
<BOX> 
<CALLOUT> 
<CALLOUT_REF> 
<CALLOUTS> 
<CENTER_LINE> 
<CHAPTER> 
<CHEAD> 


<CHECK_FOR_INCLUSION> 


<CO> 
<CODE_EXAMPLE> 
<COMMENT> 
<CONDITION> 
<CONTENTS_FILE> 


<COPYRIGHT_DATE> 
<COPYRIGHT_PAGE> 


<CP> 
<CPAREN> 
<DATE> 


<DEFINE_BOOK_NAME> 


<DEFINE_SYMBOL> 
<DEFINITION_LIST> 


<DEFINITION_LIST_HEAD> 


<DEFLIST_DEF> 
<DEFLIST_ITEM> 
<DOCTYPE> 
<DOUBLE_QUOTE> 


9-1 


<ELEMENT> 
<ELLIPSIS> 
<EMPHASIS> 
<ENDCOPYRIGHT_PAGE> 
<ENDPART_PAGE> 
<ENDTITLE_PAGE> 
<EXAMPLE> 
<EXAMPLE_ATTRIBUTES> 
<EXAMPLE_FILE> 
<EXAMPLE_SPACE> 
<FCMD> 
<FIGURE> 
<FIGURE_ATTRIBUTES> 
<FIGURE_FILE> 
<FIGURE_SPACE> 
<FINAL_CLEANUP> 
<FOOTNOTE> 
<FOOTNOTE_TEXT> 
<FOOTREF> 
<FORMAT> 
<FPARM> 
<FPARMS> 
<FRONT_MATTER> 
<GDEF> 
<GLOSSARY> 
<GREF> 

<GTERM> 
<HEADX> 
<HELLIPSIS> 
<HYPHENATE> 
<ICON> 
<ICON_FILE> 
<ICON_TEXT> 
<INCLUDE> 
<INCLUDES_FILE> 
<INDEX_FILE> 
<INTERACTIVE> 
<KEEP> 
<KEYWORD> 

<LE> 

<LINE> 
<LINE_ART> 


| 
ol 
WN 


ol 


“J 


00 


© 


N 


o 


| 
a So oR ow 6 oo 


1 | | J | tf 
aoawwdonann N 
= Oonh = © = © «I 


Toe eo oe ee Pe eee one 
oo Oo © 
oO o1 a 


ii 
co 
~ 


9-98 
9-100 
9-101 
9-103 
9-104 
9-105 
9-107 
9-108 
9-109 


Contents 


9-111. 


9-113 
9-114 
9-115 
9-117 
9-118 
9-120 
9-121 
9-122 
9-123 
9-126 


Contents 


<LIST> 

<LITERAL> 
<LOWERCASE> 
<MARK> 

<MATH> 
<MATH_CHAR> 
<MCS> 
<NESTED_TABLE_BREAK> 
<NEWTERM> 
<NOTE> 

<OPAREN> 
<ORDER_NUMBER> 
<P> 

<PAGE> 
<PARENDCHAR> 
<PART> 
<PART_PAGE> 
<PREFACE> 
<PREFACE_SECTION> 
<PRINT_DATE> 
<PROFILE> 
<QUOTE> 
<REFERENCE> 
<REVISION> 
<REVISION_INFO> 
<RIGHT_LINE> 
<RULE> 

<S> 
<SAMPLE_TEXT> 
<SET_APPENDIX_LETTER> 
<SET_CHAPTER_NUMBER> 
<SET_CONDITION> 
<SINGLE_QUOTE> 
<SPAN> 
<SPECIAL_CHAR> 
<SUBHEADx> 
<TABLE> 
<TABLE_ATTRIBUTES > 
<TABLE_FILE> 
<TABLE_HEADS> 
<TABLE_KEY> 
<TABLE_KEYREF> 


9-128 
9-135 
9-136 
9-137 
9-139 
9-150 
9-159 
9-163 
9-165 
9-166 
9-167 
9-168 
9-169 
9-171 
9-173 
9-175 
9-177 
9-178 
9-179 
9-180 
9-181 
9-183 
9-185 
9-188 
9-190 
9-191 
9-192 
9-193 
9-195 
9-196 
9-198 
9-200 
9-201 
9-203 
9-205 
9-207 
9-208 
9-210 
9-212 
9-214 
9-215 
9-217 


<TABLE_ROW> 
<TABLE_ROW_BREAK> 
<TABLE_SETUP> 
<TABLE_SPACE> 
<TABLE_UNIT> 
<TABLE_UNIT_HEADS> 
<TAG> 

<TITLE> 
<TITLE_PAGE> 

<U> 

<UNDERLINE> 
<UPDATE_RANGE> 
<UPPERCASE> 
<USER_I_MESSAGE> 
<USER_W_MESSAGE> 
<VALID_BREAK> 


<VALID_TABLE_ROW_BREAK> 


<VARIABLE> 
<VBAR> 
<X> 

<Y> 


Contents 


9-218 
9-220 
9-223 
9-225 
9-227 
9-229 
9-231 
9-232 
9-233 
9-234 
9-236 
9-237 
9-240 
9-241 
9-243 
9-245 
9-248 
9-249 
9-250 
9-251 
9-254 





APPENDIX A VAX DOCUMENT COMMAND SUMMARY 


DOCUMENT 





APPENDIX B_ USING LSE WITH VAX DOCUMENT 


B.1 USING LSE WITH VAX DOCUMENT 
Entering Source Code Using Tokens and Placeholders _ 


B.1.1 
B.1.2 
B.1.3 


Compiling Source Code 
Examples 

B.1.3.1 Lists e B—5 
B.1.3.2 Tables ¢ B—5 
B.1.3.3 Profile © B—6 


B.1.3.4 | Sample Template * B—7 
VAX DOCUMENT Tokens and Placeholders 


Contents 




















APPENDIX C MESSAGES C-1 
C.1 DOCUMENT COMMAND MESSAGES C-2 
C.2 TAG TRANSLATOR MESSAGES C-8 
C.3 TEXT PROCESSOR MESSAGES C—44 
C.4 DEVICE CONVERTER MESSAGES C—66 
C.5 INDEX FACILITY MESSAGES C-—73 

APPENDIX D SUMMARY OF VAX DOCUMENT TAGS D-1 

INDEX 

TABLES 
1-1 VAX DOCUMENT Doctypes _____sSsSsSsSsSsS—FSFSSSSSSSSSSSSSS 1-5 
1-2 VAX DOCUMENT Processors _—- ———EssSFFFFesFSSsSFSFSsSSSS—FSFSS 1-7 
2-1 Coding Special Characters SEE SSSSSSCFeFsSsSSSSSSSSSSFFSSS 2-3 
3-1 able 1ags. 2 8 a ee 3-7 
3-2 Special Table Functions == ——SEEEsS—CeFSsSSSSS—S—CeeFFFSSSSSSSSSS—COFFFSSSSSSSS 3-8 
3-3 PUCQUO AS cs eee 3-15 
3-4 Tags for Including Graphics Files .- S—S>SESESsSsSS—(CsssS 3-18 
3-5 Special Example Functions — SSS 3-21 
4-1 Destination Keywords _.sssSS——eFeFeFssFSSSSSS—OFeFeFsFSSSSS—FSSSSSSSSSSSSSSSS 4-3 
4-2 DCL Commands for Printing Files .— —>—SEESsSSSS—CSSS 4-5 
4-3 Profile Tags SSE SSSSSSSSSSSSOeeeFeSSSSSSSSSSSSSSSSSSFeF 4-10 
6-1 Element Types and Default Output of Symbol-Names —__ 6-5 
8—1 Examples of Emphasis Tags — > ———SEEsessSSSSsSSSSSSSSSS—SFSFSSF 8-3 
9-1 Supported Document Types ———~- ————EssSSSSSSSSSSFSS 9-48 
9-2 Summary of Alternate Designs for Doctypes SE 9-49 
9-3 <MATH> Expressions _ SSS 9-142 


9-4 Tags for Mathematical Functions 2 —EESSSSSS—SFSSSs 9-145 


Contents 


<MATH_CHAR> Symbols _—EESSSSSSSSSSSSSSSSSsFFFFFFSSSSSSSSSSSSSSSSSSS 9-150 
Element Types and Default Output of Symbol-Names _—__ 9-186 
Default File Types _.. sss A-3 
VAX DOCUMENT Doctypes Es —FesssSSSFFSSSSSSS—COFSSSSSSS A-4 
LSEDIT Commands __——SsSsSsSFSFSSSSSSSS—S—F—FeFeFFSFSFSFSSSSSSSSSSSSS—OeeFeFeFSFSSSSSSSSSSSSSSSSSSSSSSSSSS B-—2 


Summary of VAX DOCUMENT Tags ~~ EsssS—S D—1 


xiii 


Preface 





Document Structure 


This manual describes the VAX DOCUMENT generic markup system and the 
tags used to create all VAX DOCUMENT types of documentation. 


¢ Chapter 1 provides an introduction of the VAX DOCUMENT system. 


e Chapters 2 and 3 describe how to create input files and use basic text 
elements within those input files. 


e¢ Chapter 4 discusses processing of input files, including how to build a 
book. 


e Chapter 5 describes some methods to troubleshoot input files. 


e Chapter 6 explains how a user can cross-reference symbol-names 
throughout files and books. 


e Chapter 7 describes how to create a table of contents, an index, or a 
master index. 


e Chapter 8 explains the coding of some special VAX DOCUMENT features. 


e Chapter 9 is the reference section of the book, containing an alphabetic 
listing of all the SDML tags that are used in any doctype. Each tag is 
explained in full, with examples to illustrate the correct coding. 


e Appendix A explains the DOCUMENT command and the command’s 
parameters and qualifiers. 


e Appendix B is an overview of the Language Sensitive Editor that can be 
used with VAX DOCUMENT. 


e Appendix C lists and explains the error messages users could see when 
processing source files. 


e Appendix D is a table of all SDML tags (both global and doctype-specific). 
It also indicates in which doctype the tag is valid and summarizes the 
tag’s use. 


The VAX DOCUMENT User Manual, Volume 2 provides a description of the 
tags used in specific doctypes. 


The VAX DOCUMENT Design Samples manual provides information on each 
of the doctype designs available in VAX DOCUMENT and provides samples 
of each design. 





Intended Audience 


This book is intended for writers, editors, and general users who wish to 
produce technical manuals, brochures, or even business letters or overhead 
slides using VAX DOCUMENT. Familiarity with a text editor is Bias as 
is a basic knowledge of the VMS operating system. 
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Conventions 


Within both the VAX DOCUMENT User Manuals, Volumes 1 and 2, capitalized 
words within syntax statements indicate specific commands or keywords to be 
entered. Lowercase words indicate user-specified parameters or arguments. 
Optional items within syntax statements are enclosed in brackets. 


Within the reference chapters in the VAX DOCUMENT User Manuals, Volumes 
1 and 2, the discussion of each tag follows a fixed order. First, the name of 
the tag is followed by a brief overview that describes the purpose of the tag. 
Following the overview is a format section that displays the syntax of the tag: 
any optional or required arguments and the information required, any related 
tags, any restrictions on the use of the tag, and any required terminators. 


The category of “related tag” has been defined broadly. A tag is related to the 
tag under discussion if one of the following criterion is met: 


e It is required for use of the tag under discussion. 
e It marks a text element of the same kind as the tag under discussion. 


° It is commonly used with the tag under discussion. 


Following the format section is an optional description section. The 
description expands the overview and presents more detailed information 
on the use of the tag. Not every tag requires a description section. 


The discussion of a tag concludes with at least one example, or a reference 
to an example. The example shows how the tag is used in a source file and 
what the formatted result is when the file is processed for printing. 


Output examples within this manual may vary depending on the doctype you 
processed the example under, or depending on whether or not any doctype 
modifications have been made to your local installation of VAX DOCUMENT. 
Each output example is introduced by a form of the sentence “This example 
may produce the following output” to remind you that the output examples 
may vary. 





Associated Documents 


Xvi 


The reader of this manual should be familiar with: 
° Step-by-Step: Writing with VAX DOCUMENT 


Other books in the documentation set for VAX DOCUMENT Version 1.0 
which describe the more technical aspects of the product are: 


¢ VAX DOCUMENT User Manual, Volume 2 
¢ VAX DOCUMENT Doctype Designer's Guide 
¢ VAX DOCUMENT Installation Guide 

¢ VAX DOCUMENT Design Samples 


1 _ Introduction to VAX DOCUMENT 


The VAX DOCUMENT system for producing technical documentation is 
designed to fully automate the creation of documentation from generically 
coded input files. VAX DOCUMENT supports the creation of technical 
documentation from the earliest stages of a document’s planning to the final 
copy that emerges ready for production. 


The basis of the VAX DOCUMENT system is an integrated series of software 
processors that convert generically coded source files into formatted final 
output. This integrated system allows users to perform the following 
functions: 


¢ Write and maintain files for a document 
¢ Produce output for a wide range of devices 


e¢ Correct errors and incorporate changes into files with a text editor 


Although it uses a powerful, high-level language for text processing, 

VAX DOCUMENT is not difficult to learn. One or two trial runs of an 
input file through the processors is all you need do to get a good grasp 

of the system. It is recommended that you work through the exercises in 
Step-by-Step: Writing with VAX DOCUMENT before you begin more complex 
production tasks. 


This chapter gives a brief overview of the VAX DOCUMENT system and 
introduces concepts you need to understand and use the system. 





1.1 The VAX DOCUMENT Documentation Set 


The books in the VAX DOCUMENT documentation set are written for three 
audiences: a writer or editor who will use VAX DOCUMENT to create 
documentation, a system manager who will install and maintain the system, 
and a doctype designer who will create new doctypes for local use. The 
documentation set includes the following books: 


e Step-by-Step: Writing with VAX DOCUMENT 
e VAX DOCUMENT User Manual, Volume 1 

e VAX DOCUMENT User Manual, Volume 2 

e VAX DOCUMENT Design Samples 

e VAX DOCUMENT Doctype Designer's Guide 


New users of VAX DOCUMENT might want to start with Step-by-Step: 
Writing with VAX DOCUMENT for a beginning tutorial of how to use the 
system. The VAX DOCUMENT User Manual, Volume 1 contains more detailed 
information, including a reference chapter of the global tags (tags available 
in all the doctypes). The VAX DOCUMENT User Manual, Volume 2 contains 
detailed information on the doctype-specific tags. 
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Doctype designers might want to start with Step-by-Step: Writing with 
VAX DOCUMENT and then progress to the VAX DOCUMENT Doctype 
Designer’s Guide. The VAX DOCUMENT Design Samples shows the various 
doctype designs available in each of the VAX DOCUMENT doctypes. 


1.2 Features of VAX DOCUMENT 


The following are some of the most important features of VAX DOCUMENT. 


Text Formatting 
e Adjustable text alignment 


e All POSTSCRIPT” and LNO3 fonts support the full DIGITAL 
Multinational character set 


e Automatic page numbering 
e Automatic headers /footers 
e¢ Controllable hyphenation 
e = =Multicolumn output 


e POSTSCRIPT and LNO3 supported fonts 


Publishing 


e¢ A sophisticated table utility for creating tables in multicolumn formats 


e Automated cross-referencing 
¢ Automated collation of table of contents, chapters, and headings 


e Automated generation of indexes and master indexes 


e Automated generation of table of contents 


e =©Availability of 15 basic document designs 


¢ Batch or interactive processing support 


e Generation of footnotes in several formats 


Supported Output Devices 
e¢ DIGITAL’s POSTSCRIPT devices 


e Line printers 


e LNO3 and LNO3 PLUS laser printers 


e Terminal display, to read output on a terminal screen 


e VAX Mail format, to read from within VAX Mail 


= POSTSCRIPT is a trademark of Adobe Systems, Inc. 
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1.3 Using a Generic Markup Language 


The language that is used to mark up a file for processing through 
VAX DOCUMENT is referred to as generic because it is used, unchanged, 
to produce any type of document. Using a generic markup system requires 
a different perspective on writing than is needed when you use a formatting 
language (such as Digital Standard Runoff). It takes time to become 
accustomed to thinking solely in terms of content rather than format. 
You need not think in terms of margins, spacing, and other formatting 
characteristics. Instead, when using a markup system like VAX DOCUMENT, 
you must think in terms of text elements. This means that for each individual 
element of text, such as the start of a paragraph, an emphasized word, a 

_ heading, and so on, you identify that text element for the processor by tagging 
it. 
For example, compare a sample of Digital Standard Runoff (DSR) code to the 
code of VAX DOCUMENT. DSR is coded as follows: 


-b.1m5.nf.nj 

Here is a sample of text that could be 
processed by a text processor. 
-1m0.f.j. 


This method requires users to remember the current margins, the amount to 
indent the text, and so on, each time they type an example. Using SDML, 
the underlying format is controlled for consistency by the document type 
(doctype). The example is coded with tags that generically label the kind of 
text they are formatting: 


<CODE_EXAMPLE> 

Here is a sample of text that could be 
processed by a text processor. 
<ENDCODE_EXAMPLE> 


VAX DOCUMENT automatically specifies the correct formatting instructions 
for a chosen doctype, freeing the writer from the task of formatting text and 
allowing the writer to concentrate on the task of writing. 


The language that you use to tag a file, the Standard Digital Markup 
Language (SDML), contains a full set of tags for naming all the text elements 
commonly found in technical documentation. Tagging text elements is 
discussed in detail in Chapters 2 and 4. For now, just realize that you do 
not need to control the format as you write. The formatting is taken care of 
automatically during processing. 


All of your writing is done in an input file, which is also called an SDML file 
because of its file extension of .SDML. When you create a new file that will 
eventually be processed through VAX DOCUMENT, always give the file an 
.SDML extension. : 
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1.4 Introduction to the DOCUMENT Command Line 





One command, typed at the DCL prompt, is used to process any type of 
VAX DOCUMENT file: 


$ DOCUMENT input-file-spec doctype.design destination 
The DOCUMENT command requires three parameters: 
° Input-file-spec | 


Specifies the input file for VAX DOCUMENT. This file is by default an 
SDML file containing SDML tags. However, it may also be one of the 
intermediate files generated by VAX DOCUMENT. 


e Doctype 


Specifies the document type keyword for which the input file should be 
processed. This keyword specifies the kind of document to be created 
(a letter, a software manual, a journal article, and so on). A doctype can 
comprise several different designs; in that case, the design keyword is 
specified after the doctype keyword, separated from it by a period. 


e Destination 


Specifies the final processing destination for the input file. This keyword 
typically specifies a format used by a printer, but may specify formats for 
terminals or the VMS Mail Utility (MAIL). 


You can also add qualifiers to the DOCUMENT command to create indexes, 
master indexes, tables of contents, and to modify the default processing of 
your input file. The DOCUMENT command, parameters, and qualifiers, 
are explained in Appendix A. Chapter 4 discusses various processing tasks 
accomplished by using the command line. 


1.5 Types of Documents 


One of most powerful features of VAX DOCUMENT is its ability to format 
the same input file into a variety of document types (doctypes). The standard 
doctypes offered with the product cover a range of documentation needs. 
For VAX DOCUMENT Version 1.0, there are seven supported doctypes (see 
Table 1-1). Also, most doctypes offer more than one design. The doctypes 
are explained fully in the VAX DOCUMENT User Manual, Volume 2. 


In Table 1-1, the first design listed for each doctype is the default design. It 
is designated when you type the doctype with no design on the DOCUMENT 
command line. For example, specifying MANUAL on the command line 
defaults to MANUAL. REFERENCE. 


Se 


Table 1-1 VAX DOCUMENT Doctypes 
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Doctype 
ARTICLE 


LETTER 
MANUAL 


MILSPEC 


OVERHEADS 


REPORT 


SOFTWARE 


Design 
ARTICLE 


LETTER 
MANUAL.GUIDE 


MANUAL.PRIMER 


MANUAL.REFERENCE 


MILSPEC 


OVERHEADS 


OVERHEADS.35MM 
REPORT 

REPORT. TWOCOL 
SOFTWARE.BROCHURE 
SOFTWARE.GUIDE 
SOFTWARE.HANDBOOK 
SOFTWARE.POCKET_ 


REFERENCE 
SOFTWARE.REFERENCE 


SOFTWARE.SPECIFICATION 


Description 


‘ Creates an article format in an 85 x 11 inch format, with 


two columns for text. 
Creates memos and letters. 


Creates a user manual in a 7 x 9 inch trim size with 
numbered headings; it is intended for chapter-oriented 
tutorial material. 


Creates a user manual in a 7 x 9 inch trim size with 
unnumbered headings; it is intended for chapter-oriented 
primer material. 


Creates a user manual in an 83 x 11 inch trim size with 
numbered headings; it is intended for reference material. 


Offers a full implementation of the United States 
Department of Defense Military Specification Standard 
MIL-STD-490A and MIL-STD-2167. It accepts the full 
range of VAX DOCUMENT global tags, with the exception 
of the tags used to create part pages. 


Creates a page with an 85 x 11 inch trim size. It can be 
used to create slides that fit on overhead projectors, or 
figures that fit into an 85 x 11 inch notebook. 


Creates a 64 x 53 inch format suitable for camera-ready 
copy for making 35MM slides. 


Creates general purpose documents such as reports and 
formal outlines. 


Creates a two column format of the REPORT doctype. 


Creates a brochure in a 7 x Q inch trim size with 
unnumbered headings and sequential page numbers; it 
is intended for nonchapter-oriented material. 


Creates a users’ guide in a 7 x 9 inch trim size with 
numbered headings. 


Creates a handbook in a 7x9 inch trim size with numbered 
headings. 


Creates a pocket reference in a 55 x 7 inch trim size with 
numbered headings. 


Creates a reference manual in an 83 x 11 inch trim size 
with numbered headings. It provides various formats 
and tags for describing computer software. It is equally 
well-suited to describing information in a tutorial or in a 
reference format, and contains tags customized for use in 
describing software in either of these formats. 


Creates a specification in an 85 x 11 inch trim size with 
numbered headings. 
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1.6 Overview of the VAX DOCUMENT System 


Several integrated software tools form the components of the 
VAX DOCUMENT system. 


¢ The Standard Digital Markup Language (SDML), used for coding the 
document files as they are written, is a generic, high-level, device- 
independent markup language. It is not concerned with formatting; the 
information it conveys is information about the logical structure of a 
document. 


e Three processors process the file when you execute the DOCUMENT 
command. These work sequentially, checking and converting the 
generically marked text through intermediate files on its way to final 
printed form. Each file is given the same name as the original source 
file but suffixed with the file extension specific to that processor. You 
will notice that the file extension given by each processor (as shown in 
Table 1-2) actually identifies that the file is ready to be processed by the 
next processor in line. 


1.6.1 How VAX DOCUMENT Processes a File 


When you execute the DOCUMENT command, a file is run through three 
processes: 


1 Tag translation 
2 Text formatting 


3 Device conversion 


These three processes transform your input file into formatted copy. During 
the processing of a file, you can observe the following sequence of events on 
your terminal (or, after processing, in the log file if the file was processed in 
BATCH mode). 


First, the tag translator translates the tags in the input file. As the tag 
translator processes your file, you might see error messages on the terminal. 
For example, if you misspell a tag name or fail to use an ending parenthesis, 
an error message is displayed. Processing continues so as to find as many 
errors as possible. If you have consistently misspelled a tag, you receive 

a message only for the first occurrence of that error, then a final message 
announces how many undefined tags the tag translator saw. The tag 
translator’s output is a file with the same name as the input file but a file 
type named TEX (for example, filename.TEX). 


The text formatter reads the TEX file and formats the pages of output. This 
processor might also issue error messages. The text formatter creates a file 
suffixed with the file type extension that reflects the chosen output device. 
If you specify on the command line that you want the file processed for the 
LNO3 printer, the text in the file is proportionately spaced and the DVI file 
is named DVI_LNO3. For a line printer the DVI file is named DVI_LINE. 
For a POSTSCRIPT device, the file is named DVI_POST. For the terminal 
destinatio.., it is named DVI_TERM, and for the VMS Mail Utility, it is 
named DVI_TXT. 


1.6.2 


Table 1-2 


Processor 


The Tag 
Translator 


The Text 
Formatter 


The Device 
Converter 
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The device conversion program runs next and creates a device specific file, 
with the file type of either LN03, LINE, POST, TERM, or TT. This file reflects 
the destination that you specified on the command line. In particular, if you 
specified LNO3_LASER—PRINTER or POSTSCRIPT, the text in the file will 
be proportionally spaced, whereas if you specified LINE_PRINTER, the text 
will be monospaced. 


The device-specific file is ready for printing (or reading on an ASCII terminal 
or mailing through the VMS Mail Utility). The file is printed automatically if 
it has been run through the three processors, unless you specified /NOPRINT 
on the command line. The file output by the device converter is printed by 
default on the device associated with the destination on the command line. 


The processors are summarized in Table 1-2. 


VAX DOCUMENT Processors 


File Types 

Created Description 

TEX A macro processor that translates the source files into files used by 
the text formatter. The tag translator makes two passes over the 
source file, first checking for invalid tags and then translating the 
tags. . 

DVI_LNO3, The text formatter reads the TEX file and formats the pages of 

DVI_LINE, output. This processor also searches for errors, but only for errors 

DVi_POST in the format, not in text elements or tags. Like the tag translator, 
it may issue error messages. It creates a DVI file, suffixed by the 
destination that you specified on the command line. The DVI_LINE 
file is produced for the destinations LINE, TERM, and TXT. 
As the text formatter makes up a page, it automatically formats all 
page parameters. For example, it considers the best arrangement 
of paragraphs and text elements and appends to the page the 
appropriate running head and folio. 

LNO3, The device conversion program runs after the text formatter, and 

LINE, reads the .DV|_device file created by the text formatter. Whereas 

POST, the text formatter has already made the page and line breaking 

TERM, or decisions, based on the group of fonts in a given doctype, the device 


TXT 


converter makes the formatted file into a printable file. 


These final output files are ready to be printed, read on an ASCII 
terminal, or mailed through the VMS Mail Utility. After processing, a 
printable file is automatically printed unless /NOPRINT was specified 
on the command line. 





Informational Messages 


Each of the processors displays an informational message when the 
VAX DOCUMENT command is used interactively, as shown in the following 
example. 
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Note: 


@ $ DOCU myreport REPORT LNO3 


%DOC-I-IDENT, VAX DOCUMENT V1.0 
LTage Trans 1 a-t i:6n-)..; 
“%TAG-I-TAG_IDENT, V1.0 
%TAG-I-DEFSLOADD, End of Loading of Tag Definitions 
“%TAG-I-ENDPASS_1, End of first pass over the input 
[Text Formatting]... 
“%TEX-I-IDENT, V1.0 
“%TEX-I-PAGESOUT, 17 pages written. 
-TEX-I-QUTFILENAME, ’*DUA1: [DOCFILES]MYREPORT.DVI_LNO3’ 
[Device Conversion] 
%DVC-I-IDENT, DVC$LNO3 V1.0 
%DVC-I-PAGESOUT, 18 pages written to file: 

DUA1 : [DOCFILES]MYREPORT . LNO3 
[Printing File]... 


Job MYREPORT (queue SYS$LNO3, entry 832) started on SYS$LN03 
$ 


@ Identifies the DOCUMENT command line that you type at the DCL 
prompt. In this example, the DOCUMENT command was issued for a 

file called MYREPORT.SDML, (the SDML file type is assumed by the tag | 
translator). The file is to be processed for the REPORT doctype, and the 
output will be printed on the default LNO3 laser printer. 


On the command line, the command, qualifiers, and keywords can be 
abbreviated to the shortest unique string. For example, DOCUMENT was 
abbreviated to DOCU, and the destination, LN03.LASER—PRINTER, was 
abbreviated to LNO3. 


@ Identifies the message that indicates that the tag translator is starting to 
process the file, and will now log its activities. If there are any tag translator 
errors, they are reported at this point. 


© Identifies the point when text formatting begins. Any text formatting errors 
are seen at this point. 


© Identifies the point when device conversion begins. 


© Shows the point that the file has started printing on the specified device. 
Jobs will print by default in both interactive and batch processing. 


1.6.3 Doctype-Independent and Doctype-Specific Tags 


The majority of the SDML tags used for marking your text are valid in any 
of the doctypes. These tags are called “doctype-independent,” or “global,” as 
they work in all doctypes for which they are appropriate. For example, all 
doctypes use paragraphs and lists, so <P> and <LIST> are accepted in all 
doctypes. 


A few of the tags that are listed as global in this manual have restricted 
use, as they are not appropriate in one or more doctypes. For example, the 
doctypes LETTER or OVERHEADS do not contain front matter, such as a 
title page or preface, so the front matter tags (accepted in most doctypes) are 
restricted in these doctypes. 


Tags that are used specifically in one doctype only are called “doctype- 
specific.” For example, only a letter contains an address from the person 
sending the letter, so the doctype-specific tag <FROM_ADDRESS> can be used 
only in the LETTER doctype. 
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Appendix D lists all the global and doctype-specific tags. It also identifies the 
doctype to which each doctype-specific tag belongs. 


When first experimenting with the system, process your input file using the 
MANUAL doctype because it has no restrictions on the use of global tags. 
Later, you can experiment with the other doctypes, by reprocessing your 
SDML files and specifying the new doctype on the command line. If the 
SDML files include tags that are not recognized in the specified doctype, 
informational messages are issued, and you can either fix the errors or go 
back to using the MANUAL doctype. 


1.6.4 Context-Sensitive Tags 


Some tags are used in a group rather than individually. They are grouped 
according to function and are defined in the context of other tags. Such 
context-sensitive tags need a tag that enables the rest of the tags in that 
group. You generally place the tags in the group in a specific order, and 
terminate the ordered group with a terminating tag. For example, a table 
begins with a <TABLE> tag and ends with an <ENDTABLE> tag. Between 
these tags are additional tags that supply information about the number of 
columns, column widths, column headings; this pattern of tags is the same 
for every table. 


Other examples of global context-sensitive tags include lists, examples, and 
figures. An example of doctype-specific context-sensitive tags is the group of 
reference template tags used in the SOFTWARE doctype. 





1.7 Processing Books and Elements of Books 


You can use VAX DOCUMENT to process files that are individual 
components of a large book. A book is usually divided into chapters, whereas 
other types of documents are not chapter-oriented. In a book, each chapter is 
considered its own book element, and is kept in its own file. By setting up a 
book in this way, you can process the book’s chapters either separately or as 
a whole. The processing of a whole book is called a bookbuild. 


Processing a document in a nonbook format (not using a bookbuild) is 
generally useful when you have a smaller document and plan to process the 
entire document every time you make a change, and you are not concerned 
with maintaining cross-references in the book. A bookbuild allows you 

to build a large book and then process elements of it while maintaining 
cross-references. 


To perform a bookbuild, you must create a separate file that contains a list of 
all the book’s elements in the order that they will appear in the book. The 
separate file profiles the order of the book, from front to back, and hence 

is called a profile. The book’s profile becomes the main vehicle used for 
processing the book. 
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Creating an SDML File 


This chapter provides guidelines for creating an SDML file with 
VAX DOCUMENT. It explains the use of the various types of code in an 
SDML file, including tags and arguments. The principal rules of coding 


_ syntax are also explained. The use of these rules permits VAX DOCUMENT’s 


tag translator to recognize and act on the tags that mark your text. 





Global Tags 


In all files generically coded with VAX DOCUMENT, text must be marked, 
or “tagged,” so that the text is formatted correctly when the file is processed. 
For every text element (that is, every individually treated portion of text), you 
insert a unique ASCII character sequence to identify that type of text element. 


~-These ‘character sequences identify a paragraph as a paragraph, a table as a 


table, and soon. 


Tags are used to identify the text elements. A tag is a term or abbreviation 
enclosed in angle brackets ( <...> ). When VAX DOCUMENT processes your 
SDML file, it recognizes the tags, translates them, and formats the text. 


There are three rules concerning VAX DOCUMENT use. 


RULE #1: 


Type each tag as shown, adding no punctuation or spaces. Use angle brackets 
to enclose tags. The tag name may be in uppercase or lowercase letters, or a 
combination of both. 


Here are some sample tag formats: 


Tag Format Function 

<P> Starts a paragraph 

<CHAPTER> Marks the beginning of a chapter and specifies its title 
<TABLE> Starts a table (like this one) 

<NOTE> Starts text that receives distinctive treatment 
<ENDNOTE> Ends the text that receives distinctive treatment 


There are two types of tags: tags that mark the starting point of a text element 
(for example, <P>, <TABLE>, or <NOTE> ) and tags that completely 
encompass a text element (for example, <HEAD1> or <CHAPTER> ). Of the 
first type, some require explicit termination (for example, <NOTE> requires 
<ENDNOTE> ) and some do not (for example, <P>). All the text that lies 
between the starting and terminating tags receives distinctive treatment. 


All VAX DOCUMENT global tags are listed alphabetically and described in 
Chapter 9. The description of every tag in that chapter indicates whether that 
tag requires explicit termination. 
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2.1.1 Tag Arguments 






AN ___a backslash,-as follows: 


There are two types of tag arguments, those that provide additional 
characteristics or identify requirements of the text associated with a tag 

and those that provide actual text. Some tags require one or more arguments, 
while other tags do not require arguments but can accept them as additional 
information. Still other tags do not accept any arguments. 


An argument is enclosed in parentheses and immediately follows the closing 
angle bracket of the tag. If you use an argument with a tag that will not 
accept one, VAX DOCUMENT issues warning messages when you process 
the file. More than one argument can be included within the parentheses 
(this is called an argument list). A space or an end of line cannot separate the 
tag from its argument list. 


RULE #2: 


Supply only those arguments that are permitted by the tag’s format. Use 
parentheses to enclose arguments. 


Use a backslash (\) to separate multiple arguments. For example, the 
<CHAPTER> tag takes two arguments, a chapter title and a symbol name 
for that title. Therefore, the title for a chapter of a book would be coded with 





<CHAPTER>(Introduction to Farming\intro_farm) 


Each ta iptien-i fficludes a list of valid or required 
arguments to that tag. Use of symbol names is discussed in Chapter 6. 





2.2 Coding an SDML File 


RULE #3: 
Tag every text element. 


This rule is true whether or not the tag requires an argument list, a 
terminating tag, or both. 


For example, the following text contains two text elements and so requires 
two tags: 


<P>Employment opportunities grew throughout the company. If the president 
of the company had realized what a <NEWTERM>(matrix) would start 
developing... 


In this example, the writer started a new paragraph and so tagged it with the 
<P> tag. The writer also wanted to identify a new term in this document 
with some special format, so treated the term as an individual text element 
and tagged it. The output of this paragraph might appear like this: 


Employment opportunities grew throughout the company. If the president of 
the company had realized what a matrix would start 
developing... 


The three rules concerning the use of VAX DOCUMENT cover the 
requirements for coding any SDML file. By remembering these rules, you 
should be able to code your files with few errors. However, there are several 
special cases to keep in mind when you want to show coding characters, 
characters used by VAX DOCUMENT internally, in your output. The 
following discussion explains these unusual cases. 
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2.3 Coding Considerations 


Table 2-1 lists coding-characters that are treated in a special manner by 
VAX DOCUMENT when placed in an argument to a tag. These characters 
must be replaced by tags when you want them to appear in your output. 


Table 2—1 Coding Special Characters 


Character Placement of Character Correct Coding in Text 

<text> Angle bracket enclosing a tag <LITERAL> (text) 
name not meant to be translated. 

<tag> ( Opening parenthesis following a Leave space between the 
tag name. tag and parenthesis. 

\ Backslash in an argument. <BACKSLASH> 

| Vertical bar in an argument. <VBAR> 

& Ampersand in an argument. <AMPERSAND > 

( Unmatched opening parenthesis <OPAREN> 


in an argument. 


— 


Unmatched closing parenthesis in = <CPAREN> 
an argument. 


The tag translator displays a message when you have incorrectly used any 
of these characters in an argument. The correct coding of each of these 
characters is explained in detail in the following sections. One other special 
case, that of coding a hyphen in text, is discussed in Section 2.3.5. 


2.3.1 Coding Text that Looks Like a Tag 


Because angle brackets are used to enclose tags, be careful with your use 
of them. When a word is surrounded by angle brackets, the tag translator 
attempts to evaluate it as a tag. If it is a valid tag, it is translated like any 
other tag. If the word is not a valid tag, a warning message is issued when 
the file is processed; the word (enclosed in angle brackets) is placed in the 
output unchanged. 


For example, the following text contains the terms <reroute> and 
<return> , coded as if they are tags: 


<P>When marking packages for delivery, do not confuse the 
<reroute> destination with the <return> destination. 


During processing, the tag translator tries to translate these terms as tags. It 
produces two warning messages because <reroute> and <return> are 
not defined as valid tags. 


To avoid this problem, use the <LITERAL> tag, which directs the tag 
translator to ignore everything (including the angle bracket characters) in 

its argument. To have <reroute> and <return> appear in the text but 
not generate warning messages, the above example should be coded like this: 


<P>When marking packages for delivery, do not confuse the 
<LITERAL>(<reroute>) destination with the 
<LITERAL>(<return>) destination. 
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Note: 


Notice that the entire term that the writer wants to include in the text is 
treated as an argument to the <LITERAL> tag, including the angle brackets 
surrounding the term. 


Use the <LITERAL> tag to document any characters that are prefixed with 
angle brackets. For example, the control characters of the ASCII character set 
commonly are surrounded by angle brackets, such as <STX> or <NAC>. 
Another case where you might show an angle bracket is in an equation. For 
instance, in the equation “If M <P then ...,” the tag translator tries to define 
this as part of the paragraph tag ( <P> ), and issues a warning. 


You can place a single angle bracket anywhere in the file, as long as the 
next few characters do not look like they begin a tag. If they do look 
like tags to the tag translator but are not valid tags, you will receive 

a warning message. Coding the angle bracket within a <LITERAL> 
argument ( <LITERAL> ( <)) ensures that you will not receive a warning 
message for placing a single angle bracket in a file. 


2.3.2 Coding Opening and Closing Parentheses in an Argument 
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Note: 


When the closing angle bracket of a tag is followed immediately by an 
opening parenthesis, the tag translator assumes that an argument follows. 
The tag translator reads the argument, looking for a matching closing 
parenthesis to mark its end. If one of your arguments includes an unmatched 
closing parenthesis, the parenthesis will be mistaken for the end of the 
argument. 


If an argument needs to include an unmatched opening or closing parenthesis, 
you can code it with special tags created for this purpose. Use either 

the <OPAREN> (that is, opening parenthesis) or the <CPAREN> (closing 
parenthesis) tag. A parenthesis that is coded this way is not matched with its 
counterpart by the tag translator. It does not disturb the counting of matched 
pairs of real parentheses, nor the recognition of the true end of the argument 
list. For example: 


<HEAD1>(A (CLOSE Statement) 
must be coded as: 
<HEAD1>(A <OPAREN>CLOSE Statement) 


Outside of an argument, parentheses cause no problems. For example, the 
following line is coded correctly: 


<P>We always use a (CLOSE Statement in the code... 


You need only use the <OPAREN> and <CPAREN> tags within arguments 
because parenthesis characters have no special meaning outside of arguments. 
For more information on <OPAREN> and <CPAREN>, refer to the tag 
descriptions in Chapter 9. 


Open parentheses following tags that do not accept arguments must be 
preceded by one or more blank spaces. For example, in the following code 
a space must be placed after the <P> tag, or the text in the parentheses 
must be placed on a new line. 


<P> 
(See Section X.) 
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2.3.3 Coding a Backslash in an Argument 


A backslash is used to separate arguments. If you want to include a 
backslash character within one of your arguments, you must code it using 
the <BACKSLASH> tag. Otherwise, the backslash in your argument is 
interpreted as an argument separator. In effect, the tag translator will make 
two arguments out of what you perceive as one argument. For example: 


<P>Insert the part numbered <KEYWORD>(ABC\123) into 


The tag translator treats this as two arguments and issues an error message 
because this tag cannot accept two arguments. To include a backslash that 
will not be evaluated by VAX DOCUMENT, write the following: 


<P>Insert the part numbered <KEYWORD>(ABC<BACKSLASH>123) 
into : 


The following is produced: 
Insert the part numbered ABC\123 into 


You need to use this special coding only within arguments. For more 
information on <BACKSLASH> , refer to its description in Chapter 9. 


2.3.4 Coding a Vertical Bar or Ampersand in an Argument 


The tag translator assigns special meanings to the vertical bar (|) and the 
ampersand (&) characters, recognizing them as a pair of internal coding 
characters. When the tag translator is reading an argument list and finds a 
vertical bar, it starts looking for a matching ampersand. 


Because these tags have special meaning within argument lists, you should 
code the vertical bar character with the <VBAR> tag and the ampersand 
character with <AMPERSAND> within your arguments. You need do this 
only within arguments, however, because these characters have no special 
meaning outside of arguments. 


The following example that shows the difference between using an 
ampersand in a tag argument and using it in text: 


<HEAD3>(The Ampersand (<AMPERSAND>) Character) 


<P>The ampersand character (&) is used to continue a BASIC statement on 
the next line. ... 


Within the argument to the <HEAD3> tag, the ampersand must be coded | 
with the <AMPERSAND> tag. In the text, the ampersand can be coded with 
the ampersand character. 
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2.3.5 Coding a Hyphen in Text 


When two or three hyphens are used consecutively in proportionally-spaced 
text, VAX DOCUMENT translates them into en dashes and em dashes. 

(An en dash is slightly longer than a hyphen, and an em dash is slightly 
longer than an en dash.) This does not occur in monospaced text, such as in 
examples. 


To produce the text 1981—1983, you would type 1981 -- 1983, making sure 
to leave space between the numbers and the hyphens. VAX DOCUMENT 
interprets the two hyphens as an en dash. To produce the common 
convention of using an en dash as a minus sign, such as -12.5, you would 
type - - 12.5. 


To produce an em dash, type three consecutive hyphens — or two 
consecutive dashes surrounded by spaces. For example, to produce the 
sentence “There is still time — we have until Friday,” type either “There is 
still time - - - we have until Friday” or “There is still time -- we have until 
Friday.” 
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3.1 


Using Common Tags 


Paragraphs 


This chapter discusses the coding of text elements frequently used in almost 
every doctype. These text elements include the following: 


e Paragraphs 
e Headings 
e Chapters 


e Front Matter text elements, including title page, copyright page, and 
preface 


e Back Matter elements, including appendixes and glossary 


e —_ Lists 
e Tables 
e Figures 


e Examples 


This chapter describes some of the most basic tags used in any doctype within 
VAX DOCUMENT. The tags are also described in Chapter 9. 





A paragraph is labeled with the <P> tag. Within a doctype, the tag 
creates the same output, no matter where it is placed in a document. It is 
unnecessary to leave blank lines before or after the paragraph, or to recall any 
of the other usual formatting conventions required when a typewriter is used. 
For example, spacing, justification, and indention of a paragraph are provided 
by the specified doctype. As writer, you must only inform the text processor 
that you want this specific text element. Anywhere you place a <P> tag, the 
text processor will begin a new paragraph. The only reason that you might 
want to leave blank lines or spaces in your file is to make it easier to read 
your source file. 


The following example shows the use of the <P> tag in a doctype that calls 
for space between paragraphs, with no indentation. 


<P>The species is the basic unit of classification. Clearly, 

not all species resemble each other to the same degree or 

are closely related. <P>In any careful study, 

one of the vital early steps is the organization and naming of objects. 


Output 


The species is the basic unit of classification. Clearly, not all species 
resemble each other to the same degree or are closely related. 


In any careful study, one of the vital early steps is the organization 
and naming of objects. 


Note that the paragraphs are formatted correctly no matter how your source 
file is broken across lines. 
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3.2 


Using Common Tags 


If you want a paragraph enclosed in parentheses, be careful to place a space 
or an end of line between the tag <P> and the parenthetical text. For 
example: 


The species is the basic unit of classification. 
<p> (Clearly, not all species resemble each other to the same degree or 
are closely related.) 





Headings 


Headings are intended to label a section of text. Depending on the 
doctype, headings can be numbered automatically during processing. 
VAX DOCUMENT keeps a count of each heading level and consecutively 
numbers each heading within a level. 


A first level heading is labeled with the tag <HEAD1> and the output is in 
the form x.x. In the same way, a second level head is labeled with the tag 
<HEAD2>. You can use up to six heading levels, as required. 


The number of a chapter is not counted as a heading level. If the document 
has a <CHAPTER> tag, the chapter number is included in the heading level 
number. For example, this chapter is number 3, and so the heading level 
number of this section became 3.2. If there is no <CHAPTER> tag, only the 
heading level number is used. 


Example 


<HEAD1> (Physical Features) 
<P>Alaska consists of a compact central mass 


<HEAD2>(General Physiographic Features) 

<P>The main features are mountains 
<HEAD3>(Physiographic Features) 

<P>Between the Pacific and Rocky Mountain systems 


This example shows the use of the <HEADx> tag for creating three heading 
levels. To see the output of this example, refer to the MANUAL doctype 
chapter in VAX DOCUMENT Design Samples. 





Chapters 


The <CHAPTER> tag is used to label the chapter title at the beginning of a 
new chapter. If a source file contains a chapter in a book, the <CHAPTER> 
tag must be the first tag in the file, as it enables all cross-references within 
that file. The tag requires a chapter-title as its first argument. It can accept a 
symbol-name (for the chapter-title) as its second argument and requires one if 
the file is used in a bookbuild. 


A chapter is a basic text element in many types of documentation. However, 
it is treated as a book element during a bookbuild. You can make chapters 
of a book number correctly during processing only if the chapter is listed as 
a book element in the book’s profile, and the profile is processed through a 
bookbuild procedure. An example of the beginning of a chapter follows: 


<CHAPTER> (Introduction to VAX DOCUMENT) 
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3.4 


3.4.1 


Front Matter 


Title Page 


Using Common Tags 


In this example the chapter tag has one argument, the title for that chapter. 
The first chapter tag in a book automatically receives the chapter number 1, 
and each following chapter is incremented by one. 


If you prefer to maintain a document in a single source file, you can include 
more than one chapter in a file, and therefore more than one <CHAPTER> 
tag. The chapters are still numbered automatically. However, you would 
have to move any chapter manually if you want to reorganize the document. 





The front matter of a book typically consists of four components: 
e 6 The title page 

e The copyright page 

e The table of contents, discussed in Chapter 7 


e The preface 


The profile for your book should name a single book element as the front 
matter. This file might contain three <INCLUDE> tags to name the three 
separate SDML files that hold the title page, copyright page and preface. 
However, some writers prefer to combine the title and copyright pages into 
one file. 


The following is an example of a front matter file: 


<FRONT_MATTER> (symbol-name) 
<INCLUDE> (titleandcopy.sdml) 
<INCLUDE> (preface .sdm1) 
<ENDFRONT_MATTER> 


The title page is produced by a group of context-sensitive tags. The title page 
consists of the following tags: 


<TITLE_PAGE> 
<TITLE>(... ) 
<ORDER_NUMBER>( ... ) 
<ABSTRACT> 


<ENDABSTRACT> 
<REVISION_INFO>( ... ) 
<END_TITLEPAGE> 


The <TITLE_PAGE> tag is defined only within the context of the <FRONT_ 
MATTER> tag. The title page of this book illustrates the output of each of the 
tags. 
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3.4.2 Copyright Page 


3.4.3 Preface 


The copyright page is produced by a group of context-sensitive tags. The 
copyright page tags include: 


- <COPYRIGHT_PAGE> 


<PRINT_DATE>( . .-. ) 
<COPYRIGHT_DATE>( ... ) 
<ENDCOPYRIGHT_PAGE> 


The <COPYRIGHT_PAGE> tag is defined only within the <FRONT-MATTER> 
tag. The copyright page of this book illustrates the output of each of the tags. 


The <PREFACE> tag is defined only within the front matter. The preface 
pages of this book illustrate the output of these tags (for this book’s doctype 
and destination.) 


The preface always begins on a right-hand page following the table of 
contents, thus it always begins with an odd page number. However, because 
the table of contents is produced separately from the rest of the book, VAX 
DOCUMENT cannot automatically supply the correct starting page number 
for the preface. 


When you are doing a final bookbuild, you must determine the actual number 
of pages in the table of contents and then, if necessary, edit the file that 
contains the preface, supplying the desired page number as an argument to 
the <PREFACE> tag. 


Calculate the preface page number by adding two to the number of pages 

in the table of contents, to account for the title and copyright pages. If this 
number is even, add one to it and use the result as the argument to the 
<PREFACE> tag. For example, if the table of contents requires six pages, the 
first part of the calculation yields eight, an even number. Add one and use 
nine as the argument to the <PREFACE> tag. However, if the sum of two 
plus the number of pages in the table of contents is odd, add two to the result 
to obtain the next highest odd number. Then reprocess the front matter with 
the DOCUMENT command to obtain front matter output that displays the 
correct page numbers. 





3.5 Back Matter 


3-4 


The back matter of a book can consist of the following: 
e Appendixes 
e Glossary 


e Index, discussed in Chapter 7 


3.5.1 


Appendixes 


3.5.2 Glossary 


3.6 


Lists 
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Appendixes are structured exactly the same as chapters. They consist of 
hierarchically numbered sections containing paragraphs, illustrations, and 
so forth. Use the <APPENDIX> and <ENDAPPENDIX> tags to enclose each 
appendix. Appendixes are automatically given sequence letters in the order 
corresponding to the order in which they appear relative to one another in 
the bookbuild. 


The glossary is a simple structure that is produced using a template. The 
glossary template consists of the following pattern of tags: 


<GLOSSARY>(Glossary\gloss_chap) 


<GTERM>( ... ) <GDEF>(... ) 
<GTERM>(... ) <GDEF>(... ) 
<ENDGLOSSARY> 


The glossary begins automatically on a right-hand page with a proper 
heading. You should arrange glossary terms alphabetically. 





There are several types of lists: 


ALPHABETIC The list element identifiers are alphabetic letters. 
CALLOUT The list element identifiers are reverse-print callout numbers 
, (on supported output devices), for example @. 

NUMBERED The list element identifiers are arabic numerals. 

ROMAN The list element identifiers are roman numerals. 

SIMPLE There are no list element identifiers. 

STACKED List elements do not have identifiers, but are stacked within 
the specified set of delimiters (braces, brackets, or double 
brackets). 

UNNUMBERED List element identifiers are special characters, such as bullets. 


The following tags are needed to create any type of list: 
¢ <LIST> (with a required argument that specifies the type of list) 
e <LE> (meaning “list element”) 


be <ENDLIST> 


The following example shows the use of the <LIST> tag to create an 
unnumbered list. 


3.7 


Using Common Tags 


Example 


<P>Mammalian classification of the order Lagomorpha follows: 


<LIST> (UNNUMBERED ) 
<LE>Kingdom Animal 
<LE>Phylum Chordata 
<LE>Class Mammalia 
<LE>Order Lagomorpha 
<LE>Family Leporidae 
<LE>Genus Lepus 


<LE>Species Lepus californicus 


<ENDLIST> 


Output 


Mammalian classification of the order Lagomorpha follows: 


Kingdom Animal 
Phylum Chordata 
Class Mammalia 
Order Lagomorpha 
Family Leporidae 
Genus Lepus 


Species Lepus californicus 


As shown in this example, a <LIST> tag requires a terminating tag, 
<ENDLIST>. The <ENDLIST> tag terminates any type of list and does 
not require an argument. 


The <LE> tag identifies each element within the list. 





Tables 
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The <TABLE> tag is used to create both informal and formal tables. The two 
types of tables differ in the following ways: 


Informal Given no caption, is unnumbered and is not listed in the table 


of contents. 


Formal Given a caption and numbered. Listed in the table of contents. 


Can be referenced with the <REFERENCE> tag. 


Only four tags are required to create either type of table: 


<TABLE> 
<TABLE_SETUP > 
<TABLE_ROW> 


<ENDTABLE> 
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Table 3-1 describes the four required tags. It also describes several other 
tags that are not required to create a table but are useful to specify special 
formatting. Table 3-1 lists the tags in the order that they should be used in 
your SDML file. Note that the <TABLE_ROW> tag can be used throughout 
a table. In Table 3-1, arguments are not shown for any tag except for the 
<TABLE> and <TABLE_ROW_BREAK> tags. 


Table 3—1 Table Tags 


Tag, in order of use Description . 
<TABLE> (table-caption\symbol- Creates a table and enables all other table tags. The optional symbol- 


name) 
<TABLE_ATTRIBUTES> 


<TABLE_SETUP> 


<TABLE_HEADS> 
<TABLE_ROW> 


name argument can be used to reference the table. ' 


Specifies special formatting for the table, such as wide, multipage, or a 
table that is not to be broken between pages. The table's attributes are 
ignored if this tag does not precede <TABLE_SETUP> . 


Establishes, or “sets up,” the number of columns in the table and the 
table width. If excluded, the table will not be created. You always list 
each column width except for the width of the last column. 


Specifies headings for the table columns. 


Specifies text for one row of the table. Each argument supplies the 
text for a column in a row. Can precede or follow table units (grouped 
sections of the table) as required. Can be repeated throughout the 
sequence of table tags. 


<TABLE_ROW_BREAK> (first) Specify the boundaries within which a table can be broken onto a new 
<TABLE_ROW_BREAK> (last) page. Not required, but useful for controlling the format of the table. 


<VALID_TABLE_ROW_BREAK> Controls the pagination of long table rows. Required in tables with long 


<ENDTABLE> 


table rows. 
Terminates <TABLE> . 


‘In the <taste> tag, the table-caption argument is required in a first level formal table, but is not permitted 
in a nested table (a table embedded in another table). 


A second group of table tags exists to perform special table functions. For 
example, you can embed a heading in a table that spans several of the table’s 
columns, or you can embed a table within another table. These special 

tags are not required to create a table, but are available for more complex 
formatting needs. 


Table 3-2 lists the special table functions available, the tags required for each 
function, and the location where an example of each function can be found in 
Chapter 9. 
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Table 3—2 Special Table Functions 





Function Tags Used 


Location of Example 
of Function in 


Tag Description Chapter 9 





Aligning numbers in <ALIGN_CHAR> 


a table. 


Nesting (embedding) 
a table within 
another table. 


All table tags are used. 
<NESTED_TABLE_ 
BREAK> is required. 


Creating a table key <TABLE_KEY > 
(legend) to explain 


abbreviations used in 


the table. 
<ENDTABLE_KEY > 
<TABLE_KEYREF> 
Embedding a <SPAN> 
heading in a table 
that spans the length 
of several table 
columns. 
<RULE> 
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Specifies a special character See <ALIGN_CHAR> 
that is replaced by a space 

wherever it appears in table 

rows. The character can 

be used to achieve vertical 


alignment within a column. 


See <NESTED_TABLE_ 
BREAK> 


Marks a place that a nested 
table may be broken across 
pages. 


Begins a key for the table. If See <TABLE_KEY> 
used, it must follow <TABLE_ 


SETUP> . 


Terminates the <TABLE 
KEY> tag. 


Specifies that the table key 
or legend should be printed 
below the table. Required if a 
table key or legend is included 


in the table. 


Causes a heading to span See <TABLE_UNIT> 


more than one table column. 


Specifies that a horizontal 
rule should appear below the 
embedded heading. 


Table 3—2 (Cont.) Special Table Functions 
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Function Tags Used 


Location of Example 
of Function in 


Tag Description Chapter 9 





Grouping sections of = <TABLE_UNIT> 
a table and labeling 


the sections. 
<TABLE_UNIT_HEADS > 


<ENDTABLE_UNIT > 


Including in the <TABLE_FILE> 
source file a 
separate file that 


contains a table. 
Referring to the 
symbol-name given 
to the table. 


<REFERENCE > 


Example 


<P>See <REFERENCE>(heart_rate_tab) for a list of 
the heart rates of selected mammals. 


Divides a table into groups. See <TABLE_UNIT> 
The groups can have headings 


within the table. 


Specifies the table unit 
headings. If used, must 
follow <TABLE_UNIT> . 


Terminates the <TABLE 
UNIT> tag. 


Includes a separate file which 
contains a table. Not required. 


See <TABLE_FILE> 


If a symbol name is specified See <REFERENCE> 
ina <TABLE> tag, this tag 

can be used to reference the 

symbol name in other places 

in the document, thereby 

always producing the correct 


table number and caption. 


<TABLE>(Heart Rates of Selected Mammals\heart_rate_tab) 


<TABLE_ATTRIBUTES> (keep) 
<TABLE_SETUP>(3\19\16) 


<TABLE_HEADS>(Common Name\Weight\Heart Rate, Beats per Minute) 


<TABLE_ROW>(European hedgehog\500-700 g.\246) 
<TABLE_ROW>(Gray shrew\3-4 g.\782) 
<TABLE_ROW>(Least chipmunk\40 g.\684) 
<TABLE_ROW>(Gray squirrel\500-600 g.\390) 
<TABLE_ROW>(Harbor porpoise\170 kg.\40-110) 
<TABLE_ROW>(Mink\0.7-1.4 kg. \272) 
<TABLE_ROW>(Harbor seal\20-25 kg. \18-25) 
<ENDTABLE> 


The output of this example follows: 


Output 


See Table x—x for a list of the heart rates of selected mammals. 
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3.7.1 
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Table x—x Heart Rates of Selected Mammals 


Common Name 


European hedgehog 


Gray shrew 


Least chipmunk 


Gray squirrel 


Harbor porpoise 


Mink 
Harbor seal 


Weight Heart Rate, Beats per Minute 
500-700 g. 246 

3-4 g. 782 

40 g. 684 

500-600 g. 390 

170 kg. 40-110 

0.7-1.4 kg. 272 

20-25 kg. 18-25 


Controlling Table Attributes 
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You can control the following attributes of tables: 
e  Formality (that is, if the table has a number and a caption or not) 
e Its overall width and the size of the text 


e Whether it is allowed to break across pages or if the entire table must be 
kept on a single page 


The formality is controlled by the presence of the caption argument in the 
<TABLE> tag. If you do not specify this argument, no number is assigned to 
the table. Tables are automatically numbered. The numbers are sequential 
throughout a document, or numbered beginning at 1 in each chapter. 

With the exception of the REPORT document type, you cannot control 

the numbering; that is an attribute of the overall document type and design. 


You have control over the table attributes of width (the table’s margins) and 
page-breaking. These two attributes are discussed in the following sections. 


Controlling a Table’s Margins 
The width of a table, that is the left and right margins, is determined by the 
following default attributes: 


e For formal tables, the left margin of the table is, by default, the same as 
the normal left margin of text, regardless of whether the text immediately 
preceding the table is indented. 


e For informal tables, the left margin of the table is the same as the current 
left margin of the text. If the text is indented, (for example if it is a list 
element) the table is indented at the same margin. 


e In either case, the right margin of the table is always the same as the 
right margin of the text. 


Common Name 
European hedgehog 
Gray shrew 

Least chipmunk 
Harbor porpoise 
Mink 

Harbor seal 
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For example, if you coded Table x-x without arguments to the <TABLE> tag, 
and in the context of a list, it would be output as follows: | 


Output 


e These are the heart rates: 


Common Name Weight Heart Rate, Beats per Minute 
European hedgehog 500-700 246 

Gray shrew 3-4 g. 782 

Least chipmunk 40 g. 684 

Harbor porpoise 170 kg. 40-110 

Mink 0.7-1.4 kg 272 

Harbor seal 20-25 kg. 18-25 


If you specify table width values that extend the table beyond the right 
margin of text, the following actions occur: 


e The text formatter makes an attempt to switch the size of the text in the 
table to a smaller size to see if the table will fit. 


e If the table still does not fit, the text formatter issues a warning message; 
the device converter normally issues a message also. These messages 
alert you that you must make some adjustments in your table. 


In many cases, you can lower the width values to the <TABLE_SETUP> tag to 
reduce the widths of the individual columns. 


In some doctype designs, there is a wide left margin. In those doctypes, 
the keyword attribute WIDE to the <TABLE_ATTRIBUTES> tag tells the text 
formatter to use the full page width for the table. Here is the same table 
coded with <TABLE_ATTRIBUTES> (WIDE): 


Weight Heart Rate, Beats per Minute 
500-700 246 

3-4 g. 782 

40 g. 684 

170 kg. 40-110 


0.7-1.4kg 272 
20-25 kg. 18-25 





The <TABLE_ATTRIBUTES> tag, if specified, must precede the <TABLE_ 
SETUP> tag in your SDML file. 


You can use the attribute WIDE to avoid having the text formatter switch 
to a smaller text size. If you require the smaller text size, you can specify 
<TABLE_ATTRIBUTES> (MAXIMUM). 
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3.7.1.2 


Controlling Page Breaks in Tables 

One of VAX DOCUMENT’s more powerful features is its ability to handle 
long tables, that is, tables that require more than a page of output. By default, 
when the text of a table does not fit on a single page, VAX DOCUMENT 
assumes that it can break the table across pages, and prints as much of the 
table as it can on each page. 


When a table is continued across several pages, the text formatter repeats the 
following text at the top of the second page and each subsequent page of 
output: 


e The table number and caption (with the text “Cont’d”) if the table is a 
formal table! 


e The table column headings, if any 


If a table is short and you want to keep it on a single page, you can specify 
<TABLE_ATTRIBUTES> (KEEP). In this case, the text formatter determines if the 
table fits on the current page. If the table does not fit, the text formatter starts 
a new page of output, leaving the page preceding the table short, that is, with 
blank space at the bottom. 


You can control the page breaks in multipage tables in several ways: 


e Use both the <TABLE_ROW_BREAK> (FIRST) and <TABLE_ROW_ 
BREAK> (LAST) tags to indicate good first and last places at which page 
breaks are allowed. 


¢ Group sequences of table rows that must be kept together using the 
<TABLE_UNIT> tag. 


In some cases, you may also need to provide special information to the text 
formatter to help in breaking complex tables. 


The following list summarizes the rules for breaking tables. If you are having 
difficulty getting a table to come out correctly, review these rules to see what 
you might need to do. 


Rules for Page Breaking in Tables 
The following list gives some basic rules for page breaking within tables. 


¢ | <TABLE_ROW_BREAK> (first) specifies the first place within a table at 
which a page break is acceptable. You can choose this based on the text 
in the table rows themselves. For example, if each row in the table has 
only a single line of text, you would probably place the <TABLE_ROW_ 
BREAK> (first) tag after 3 or more <TABLE_ROW> tags. On the other 
hand, if each row in the table (or even just the first) has ten or more lines 
of text, you might want to allow breaking after the first row. 


¢ § <TABLE_ROW_BREAK> (last) specifies the last place within a table at which 
a page break is acceptable. 


e¢ Between these two tags, the text formatter assumes that it is okay to break 
the table between any two table rows. It assumes that all text before the 
first place and after the last place must be on the same page. If the text 
before the first place or after the last place is more than a page, the text 
formatter chooses a place to break the table anyway. 


1 The continued caption’s placement and the continuation text may vary from one doctype to another. 
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If you do not specify these tags, the text formatter first tries to keep the 
entire table on one page. If the table does not fit, it breaks the table 
anyway, fitting as much as it can on each page. | 


By default, all table rows within the bounds of a table unit are places 
where page breaks must not occur. Therefore, the text formatter will 
always try to keep all the rows in a table unit on the same page. If the 
table unit does not fit on the page, it breaks the table anyway, fitting 
as much as it can on each page. Within the bounds of <TABLE_UNIT> 
and <ENDTABLE_UNIT> , you can specify <TABLE _ROW_BREAK> (FIRST) 
and <TABLE_ROW_BREAK> (LAST) tags to indicate the best first and last 
places, as in the table itself. 


If a table has footnotes, the text formatter does all the page breaking. The 
<TABLE_ROW_BREAK> tags are ignored. 


By default, the text formatter never breaks a table in the middle of a table 
row. Consider the following example of a table row: 


(this text may be 
a half-page or more 
in length.) 


Because the text formatter always tries to keep this table row on the same 
page, you might get short, uneven pages. If you want to allow page 
breaks within a table row, use the <VALID_TABLE_ROW_BREAK> tag in the 
middle of the column of the table row: 


<table_row>(column 1 text \ column 2 text 


) 


You should generally put the <VALID_TABLE_ROW_BREAK> tag 
immediately before a <P>, <LIST>, or <LE> tag. The <VALID_TABLE_ 
ROW_BREAK> tag is valid only in two- and three-column tables, and is 
only valid in the last column of the table. 


The text formatter’s rule about never breaking a table in the middle of a 
table row also applies if a column in a table row contains a nested table. 
For example: 


<table_row>(column 1 text \ column 2 text 


<table> 
<table_setup>(2\10) 
<table_row>(one\two 
<p> this is now text in a nested table. 


Sometimes this text gets long, too.) 
<endtable> 
) 
To specify that it is allowable to break a page within this nested table, 


you must use the <NESTED_TABLE_BREAK> tag. Like all the table page 
breaking tags, this tag does not cause the text formatter to a new page, 
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Figures 
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but it indicates an acceptable page breaking point. This tag should be 
placed just before <P> or <LE> tags, where there is already some 
vertical space. For example: 


<table_row>(column 1 text \ column 2 text 


<table> 
<table_setup>(2\10) 
<table_row>(one\two 
<p> this is now text in a nested table. 


Sometimes this text gets long, too. 
<nested_table_break> 

<p>Here is some more text for this 
column. 


) 
<endtable> 
) 
e The more places you indicate acceptable page breaks in a table, the better 


the text formatter is able to select the best page breaks and not cause a lot 
of short, uneven pages. 


e If you specify KEEP when you code a table tag, the text formatter tries to 
keep the table all on one page, no matter if it is too long. You receive a 
warning message that a page is too long, the device converter also issues 
an error message, and the part of the table that did not fit on the page 
probably will not print in the output. 


e Use the <PAGE> or <FINAL_CLEANUP> (PAGE_BREAK) tags in tables 
to control paging explicitly. Note, however, that when you control page 
breaks, you might have unexpected results when you modify the input 
file for a device other than the one for which you coded the page breaks. 


Whenever the text formatter detects a possible problem, it issues an 
informational message to alert you to check your output. 





Use the <FIGURE> tag to indicate a text element that illustrates a point. It 
might be a graphic file, a hand-drawn illustration that you need to paste in 
your output file, or a series of keystokes that represents an item in a diagram. 


A set of required tags identifies the text as a figure, establishes the figure’s 
attributes, and identifies the end of the figure. A separate set of figure tags 
can be used to identify whether the figure is line art, an icon, located in a 
different file that you want included, or simply blank lines that you want 

inserted so that a figure can be pasted in later. 


The tags that enable the context of a figure are <FIGURE> (figure- 
caption\symbol-name) and <ENDFIGURE>. Within these two tags, you 
must include at least one tag that labels the figure text element. 


Table 3-3 summarizes the figure text element tags available for use in 
figures. 


3.8.1 


Table 3-3 Figure Tags 


Function 


Including in the source file a 
separate file that contains a 
figure. 


Leaving blank space for a 
figure. 


Including a section of code 
as a figure. 


Including a figure that 
specifies a dialogue 
between the system and a 
user. 


Identifying a rough sketch 
produced at the keyboard 
for draft output. 


Including an illustration of 
sample text. 


Estimating a good page 
breaking point in a long 
figure. 


Referring to the symbol- 
name given to a figure. 


Figure Elements 


Tags Used 
<FIGURE_FILE> 


<FIGURE_SPACE> 


<CODE_EXAMPLE> 


<INTERACTIVE> 


<LINE_ART > 


<SAMPLE_TEXT> 


<VALID_BREAK> 


<REFERENCE > 
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Description of Each Tag, Location of 
Example in Chapter 9 


Includes a separate figure file. See 
<FIGURE_FILE> . 


Leaves space for a figure to be pasted in 
during production. See <FIGURE_SPACE> . 


Marks a section of code. See <CODE_ 
EXAMPLE> . 


Marks a system and user dialogue. See 
<INTERACTIVE> . 


Identifies the following text as line-art. See 
<FIGURE> . 


Distinguishes an illustration of sample text 
from the surrounding text. See <SAMPLE_ 
TEXT>. 


Indicates an acceptable page breaking point. 
Used in the context of <CODE_EXAMPLE> 
or <INTERACTIVE> . See <VALID_BREAK> . 


If a symbol-name is specified in a 
<FIGURE> tag, you can reference the 
symbol-name in other places in your 
document via this tag. See <REFERENCE> . 


When placing a figure in your input file, the tags that you use to label the 
figure as a text element must be used in the context of a <FIGURE> tag. The 
figure element (for example, a code example or a figure file) is enabled by 
<FIGURE>. The <FIGURE> tag, itself, does not include the figure element, 
but assigns the figure’s caption and the figure’s symbol-name (if used). 


Choose the figure element tag based on the type of figure. The valid tags are 
included in Table 3-3. A figure can consist of more than one type of figure 
element, and the types of figure elements can be mixed. For example, you 
can label a small graphic file and some text that accompanies it by using a 
<FIGURE_FILE> and a <SAMPLE_TEXT> tag: 


<FIGURE>(How to Load a Tape\tape_fig) 


<FIGURE_FILE>(LNO3\mydisk: [mydirectory]tape_fig.six\10) 
<SAMPLE_TEXT> 
<P>This figure illustrates how to load a tape... 
<ENDF IGURE> 


The output of this example would be a formal figure titled “How to Load a 
Tape.” The figure in [mydirectory]tape_fig.six would be included, along with 
the sample text explaining the figure. 
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You can control the following attributes of figures: 
e Formality (that is, if the figure has a number and a caption or not) 
e The margin at which the caption is printed, if the figure has a caption 


e Whether it is allowed to break across pages or if the entire figure must be 
kept on a single page, or whether it is allowed to “float” 


The formality is controlled by the presence of the caption argument in the 
<FIGURE> tag. If you do not specify this argument, no number is assigned 
to the figure. Figures are automatically numbered. The numbers may be 
sequential throughout a document, or numbered beginning at 1 in each 
chapter. With the exception of the REPORT document type, you cannot 
control the numbering; that is an attribute of the overall document type and 
design. 


The attributes that you have more control over are the margins and the 
page-breaking. These attributes are discussed in the following sections. 


Controlling a Figure’s Margins 
The width, that is the left and right margins of a figure, is determined by the 
following default attributes: 


e For formal figures, the left margin of the figure caption is the same as 
the normal left margin of text, regardless of whether the text immediately 
preceding the figure is indented. 


e For informal figures, the left margin of the figure caption is the same as 
the current left margin of the text. If the text is indented (for example, if 
it is a list element) the figure is indented at the same margin. 


The body of a figure, that is, the set of tags that specify the content of the 
figure, is processed independently of the <FIGURE> tag and its caption. For 
example, some writers use the <FIGURE> tag to formalize examples so that 
they can refer to them from anywhere in a document. For example: 


<FIGURE>(Status Message\stat_fig) 

<FIGURE_ATTRIBUTES> (WIDE) 

<CODE_EXAMPLE> (WIDE) 

%SYSTEM-S-SUCCESS, YOU HAVE SUCCESSFULLY COMPLETED ALL THE EXERCISES 
<ENDCODE_EXAMPLE> 

<ENDF IGURE> 


Here, the WIDE attribute is specified in both the <FIGURE> tag and in the 
<CODE_EXAMPLE> tag to ensure that the caption will align with the example 
text. You must use the WIDE attribute in the context of the figure’s content 
as well as in the <FIGURE_ATTRIBUTES> tag. 


3.8.2.2 
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Controlling Page Breaks in Figures 

The body of a <FIGURE> may consist of one or more individual elements; 
for instance, two or more graphics figures may comprise a single figure, 

or monospaced examples may be mixed with graphics in a figure with a 
single label. Or, a figure may consist of a monospaced example that is more 
than a page in length. In these cases, you should be aware of the rules aCe 
controlling page breaks in figures. 


By default, the text formatter makes the following assumptions about a figure: 
e It is less than a single page in length 


e If it is a formal figure, it is allowed to “float,” that is, if it does not fit 
immediately following its preceding text on a page, the text formatter 
moves the figure (usually to the top of the next page of output), and fills 
it in with text to avoid making a short page 


e If it is an informal figure, it is not allowed to float 
You can use the attribute keywords NOFLOAT and MULTIPAGE in figures 


as follows: 


¢ NOFLOAT tells the text formatter that you do not want the figure to float, 
regardless of whether a page is short 


e MULTIPAGE tells the text formatter that the figure has several elements 
and that page breaks are legal between the elements 


If a figure that requires more than a page is coded without the MULTIPAGE 
attribute, the text formatter issues a message and breaks the figure anyway, 


_ according to the following rules: 


e If the figure consists of multiple elements such as <FIGURE_SPACE> , 
<FIGURE_FILE> , and so on, the text formatter will only cause a page 
break between the individual elements. 


e Ifa figure consists of a monospaced example that is more than a page in 
length, the text formatter chooses page breaks based on the following: 


— If the example contains <VALID_BREAK> tags, the text formatter uses 
their positions as valid page break points 


— Ifthe example contains no <VALID_BREAK> tags, but has blank lines, 
the text formatter chooses the blank lines as valid page break points 


— If the example contains neither <VALID_BREAK> tags nor blank lines, 
the text formatter puts as much text as possible on each page and 
breaks the table at the bottom of the page 


e Use the <PAGE> or <FINAL_CLEANUP> (PAGE_BREAK) tags in figures 


to control the page breaking explicitly. Note, however, that when you 
control the page breaks, you may have unexpected results when you 
modify the input file or process the input file for a device other than the 
one for which you coded the page breaks. 
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3.8.3 Including Graphics Files 


Table 3-4 describes the tags that are used for including graphics in source 
files. 


Table 3—4 Tags for Including Graphics Files 


Description of Each Tag, Location of 


Function Tags Used to Do Function Example in Chapter 9 
Enabling a small graphics <ICON> This feature has several restrictions. Refer 
file to be placed in your to the restrictions in the tag description. 
‘text. See <ICON>. 

<ICON_FILE> Identifies the graphics file to be included 


in your text. This tag must be used in the 
context of the <ICON> and <ENDICON> 
tags. 


<ICON_TEXT> Accompanies an icon file with text. Must 
be used in the context of the <ICON> and 
<ENDICON> tags. 


<ENDICON> Terminates the <ICON> tag. 
Including in the source file a = <FIGURE_FILE> Includes a separate figure file. Valid only 
separate file that contains a within the context of <FIGURE> and 
figure. <ENDFIGURE> . See <FIGURE_FILE> . 


An example of a figure follows: 


Example 


<FIGURE>(Keypad Illustration) 

<FIGURE_ATTRIBUTES> (Float) 
<FIGURE_FILE>(1n03\mydisk: [mydirectory] keypad.six\22) 
<FIGURE_FILE>(post\mydisk: [mydirectory] keypad. ps\22) 
<ENDF IGURE> 


This example contains a figure file that includes another file (a graphics file) 
in this location. The tag requires the graphics file’s specification. Chapter 9 
contains full descriptions of all the figure tags, including <FIGURE_FILE> . 
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Output 


Figure x—x Keypad Illustration 
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3.9 Examples 


An example is used to display an excerpt of a programming or command 
language, the interaction between a user and the system, and the like. There 
are two types of examples in VAX DOCUMENT, informal and formal. Both 
types require their own set of tags. 


The two types of examples differ in the following ways: 


Informal Remains unnumbered and is not listed in the table of contents. 


Formal Given a caption and numbered. Listed in the table of contents. 
Can be cross-referenced with the <REFERENCE> tag. 


3.9.1 Informal Examples 
To create an informal example, use the <CODE_EXAMPLE> and <ENDCODE_ 


EXAMPLE> tags to label your text or code excerpt. An informal example 
follows. 
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Example 


<CODE_EXAMPLE> 

$! 

$! The next two lines redefine the cmd. line prompt to be the node 
$!  name’s initial. 

$! 

$ NODE :==’F$LOGICAL("SYS$NODE") ’ 

$ SET PROMPT="’’F$EXTRACT(1,1,NODE)’:" 

$! 

<ENDCODE_EXAMPLE> 


Output 


$! 

$! The next two lines redefine the cmd. line prompt to be the node 
$! name’s initial. 

$! 

$ NODE :==’F$LOGICAL("SYS$NODE") ’ 

$ SET PROMPT="" ’F$EXTRACT(1,1,NODE)’:" 

$! 


3.9.2 Formal Examples 
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To create a formal example, use the <EXAMPLE> (example-caption\symbol- 
name) and <ENDEXAMPLE> tags to label your text. 


The example shown in the previous section could be made into a formal 
example as follows: 


Example 


<EXAMPLE>(Login Commands \login_exam) 
<CODE_EXAMPLE> 

$! 

$! The next two lines redefine the cmd. line prompt to be the node 
$!  name’s initial. 

$! 

$ NODE :==’F$LOGICAL("SYS$NODE") ’ 

$ SET PROMPT="’ ’F$EXTRACT(1,1,NODE)’:" 
$! 

<ENDCODE_EXAMPLE> 

<ENDEXAMPLE> 


Output 


Example x—x Login Commands 





$! 

$! The next two lines redefine the cmd. line prompt to be the node 
$! name’s initial. 

$! 

$ NODE :==’F$LOGICAL("SYS$NODE") ’ 

$ SET PROMPT="’ ’F$EXTRACT(1,1,NODE)’:" 

$! 
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For the purposes of the text formatter, the <FIGURE> tags and the 
<EXAMPLE> tags are similar in function. The example and figure tags 
provide an alternate way to label (for cross-referencing purposes) a distinct 
type of example. See Section 3.8.2 for an explanation of how attributes 
are processed and how to control page breaks in multipage examples (the 
information in that section applies to both figures and examples.) 


In addition to the tags listed for a formal example, you can use any of a 
second group of example tags inside a formal example to do a specialized 
function. Table 3-5 lists possible special functions and the associated tags, as 
well as the location of examples of the functions in Chapter 9. 


Table 3-5 Special Example Functions 





Function Tags 


Beginning an example of <INTERACTIVE> 


interactive dialog 
<$> 
<U> 


Specifying a wide format <EXAMPLE_ 
for the example. ATTRIBUTES> (wide) 


Estimating a good page <VALID BREAK> 
break point in a long 


example. 


Specifying exact placement <EXAMPLE _ 
of the example on the page. ATTRIBUTES> (nofloat) 


Leaving blank space for an <EXAMPLE_SPACE> 
example. 


Including a separate <EXAMPLE_FILE> 
example file to be placed in 


your source file 


Referring to a symbol-name <REFERENCE> 
given to an example. 


Description of Tags, Location of Example 
in Chapter 9 


Enables the <S> and <U> tags to 
distinguish system text from user text. See 
<INTERACTIVE> and <U>. 


Labels the system text of an interactive 
example. See <INTERACTIVE> . 


Labels the user text of an interactive 
example. See <INTERACTIVE> . 


Formats the example’s caption as wide. 
See <EXAMPLE> . 


Indicates an acceptable page breaking point. 
See <VALID_BREAK> . 


Specifies special formatting for the example. 
See <EXAMPLE> . 


Leaves space for an example to be pasted 
up during production. See <EXAMPLE_ 
SPACE> . 


Causes the entire contents of the specified 
file to be included in your source file. See 
<EXAMPLE_FILE> . 


If a symbol-name is specified in an 
<EXAMPLE> tag, <REFERENCE> can be 
used to reference the symbol-name in other 
places in the document, thereby always 
producing the correct example number. See 
<REFERENCE> . 
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4s Processing and Printing Files and Books 


Chapters 2 and 3 describe the basics of using the VAX DOCUMENT system, 

including how to create an input file and how to code the basic text elements 
of an input file. After you correctly code input files, the next step is to process 
the files and print or read them on various supported devices. 


Processing and printing are done by using the DOCUMENT command 
line. The components of the command line are discussed in Appendix A. 
This chapter describes the specific use of these components for processing 
an individual file or a group of files, and identifies several command line 
qualifiers used to enhance the process. 


Appendix A describes the processing commands and qualifiers that are 
available from the VAX DOCUMENT command line. 





4.1 The Four Types of Processes 


The DOCUMENT command is used to process your input files in any of four 
ways: 


¢ As an individual file (processed in a file build) 


You have an individual file that contains all the SDML tags required to 
create an entire document. For example, a file containing a letter or a 
set of overhead slides normally contains all the tags for the complete 
document. An individual file can contain several chapters, and when 
processed, the chapters are automatically numbered in the order that 
you place them in the file. Processing individual files is discussed in 
Section 4.3. 


e As a book (processed in a bookbuild) 


You have a set of SDML files, each of which contains a portion of a 
book. To do a bookbuild, you must put the text and SDML tags for each 
individual chapter in a unique file. You then create a file called a profile 
that lists the files that contain the individual chapters. Bookbuilding is 
discussed in Section 4.5. 


e As an element of a book (processed in a book element build) 


An element is a single file that is a part of a book; for example, the tags 
and text for a single chapter. When you have made extensive changes to 
an element of a book, or when a colleague requests a copy of a particular 
chapter, you can use an element build to process and print the single 
chapter only. Book element processing is discussed in Section 4.6. 


e Asa subelement of a book (processed in a book subelement build) 


A book element can be divided into smaller parts, with each part kept 
in its own file. Each is considered a subelement of the book, and can be 
processed individually. Subelement processing is discussed in Section 4.7. 
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Processing a file that is an element or subelement of a book is useful if you 
need only part of a book for review purposes or if you want to make sure that 
your references to other parts of the book are correct after you make changes 
to the input file. You do not have to process the entire book to resolve the 
references correctly. (Using cross-references is discussed in Chapter 6.) 





4.2 Chain of Processing 


A chain of processing events occurs when an input file is run through 

VAX DOCUMENT. Each processor creates an intermediate file and passes 
that file on to the next processor. The input file is processed in the following 
order: 


1 The tag translator creates a .TEX file. 
2 The text formatter creates a .DVI_device file. 


3 The device converter creates an output specific file, with the file type of 
LNO3, LINE, POST, TERM, or TXT. This final file is sent to the output 
device for printing or reading through the VMS Mail Utility or on the 
terminal screen. 


No matter the type of build, the input file you specify on the command line is 
processed in the order of the tag translator, the text formatter, and the device 
converter, and then sent to a print queue. It is possible to specify that one 
or more processors should be skipped during the processing of a file. The 
reasons for doing this and the qualifiers used are discussed in the following 
sections. 





4.3 Processing Individual Files 


A single generically coded input file can be processed and printed on a 
hardcopy device, viewed on a terminal screen, or viewed from within 
electronic mail. 


After creating an input file, you process it by typing the DOCUMENT 
command line: 


$ DOCUMENT input-file-spec doctype.design destination 


This command line processes the input file for the chosen doctype and sends 
it to the specified destination for printing. The command line parameters 
must be specified in the order shown. 


On the command line, the input-file-spec is the name of the input file you _ 
want to process. Usually, you do not have to specify the file type of the input 
files VAX DOCUMENT assumes the correct file type. 


The doctype for your file is the second parameter on the command line. The 
doctype you choose depends on the type of information you are documenting 
and on the document design you prefer. Certain doctypes contain tags 
specific to certain types of information. For more information on these 
doctype-specific tags, see VAX DOCUMENT User Manual, Volume 2. If you 
are not sure which doctype to use, you can look through VAX DOCUMENT 
Design Samples to choose an appropriate document design. 


4.4 


Note: 
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Specify the destination to which you intend to send the output as the third 
parameter. When processing an individual file, you can specify any of five 
destinations on the command line: three supported types of printers, a 
terminal, and an electronic mail destination. The keywords you use to specify 
these destinations are shown in Table 4-1. 


Your system manager may set up site-specific destination keywords for your 
installation. Destination keywords can be abbreviated. 


Table 4—1 Destination Keywords 


Keyword Destination 

LINE_PRINTER Any line printer supported at your site. Produces a file 
that uses overstriking to achieve bold and underlined 

text. 

LNO3_LASER_PRINTER The DIGITAL LNO3 or LNO3_PLUS laser printers. 

MAIL Electronic mail. Produces a file that does not display 
bold or underline characters. 

POSTSCRIPT Any supported POSTSCRIPT device. 

TERMINAL Any ANSI terminal, such as the VT100, VT200 or 


VT300 series. Produces a file that uses ANSI control 
sequences to achieve bold and underlined text. 


The command line accepts qualifiers to control aspects of the processing. 
Those qualifiers are discussed in this chapter; the entire set of qualifiers is 
explained in Appendix A. The appendix lists the qualifiers in a standard DCL 
format. 


After being processed, the file is printed automatically (except when using the 
terminal or mail destinations) unless you specify the /NOPRINT qualifier on 
the command line. 


When processing interactively, it is good practice to use the /LIST 
qualifier on the DOCUMENT command line to capture any error 
messages. The LIS file that is created to hold the messages is placed 
in your current directory and named input-file-spec.LIS. To use this 
qualifier on the command line, type the following command line: 


$ DOCUMENT input-file-spec doctype destination /LIST 





Controlling File Processing 


So far, this chapter has mentioned several qualifiers that, when added to 
the command line, allow you to process book elements, include other input 
files into the final output, or map the files processed during a bookbuild. 
DOCUMENT command line qualifiers also can be used to control how 
processing occurs, which processors will be used, and what portion of a 
document gets processed. 
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Each qualifier should be specified on the command line only once. If 
a qualifier is specified twice, only the second qualifier takes effect. The 
qualifiers discussed in this section include the following: 


/BATCH Causes the process to be done in batch mode. 
/CONDITION Sets a condition for the file being processed. 
/DEVICE=(HORIZONT AL _OFFSET=points) Each of these qualifiers alters the default position of the 
/DEVICE=(VERTICAL _OFFSET=points) text page for the whole document. 

/DEVICE=(ST ARTING_PAGE=folio) Each of these qualifiers processes and prints only those 
/DEVICE=(ENDING_PAGE=folio) pages selected. 
/DEVICE=(NUMBER_OF_PAGES=total-pages) 

/INCLUDE Includes an additional file in the front of the input-file. 
/KEEP Specifies that the intermediate files should be kept in the 


/NODEVICE_CONVERTER 
/NOTAG_TRANSLATOR 
/NOTEXT_FORMATTER 


/SYMBOLS 


current directory. 


Processes a file without running it through the device 
converter. 


Processes a file without running it through the tag 
translator. 


Processes a file without running it through the text 
formatter. . 


Includes a file containing symbol name definitions for 
symbols that are referenced in a source file. 


Keeping Intermediate Files (Using /KEEP) 


By default, the intermediate files are automatically deleted from your directory 
after they are used in the processing chain. You can keep the intermediate 
files for later use by specifying the /KEEP qualifier on the command line. 


If you keep the intermediate files, you can reprocess a document from any 
stage of the processing chain. By specifying the appropriate combination of 
command line qualifiers, processing starts at the specified point: 


To start the processing chain after tag translation, specify /NOTAG— 
TRANSLATOR on the VAX DOCUMENT command line. You must have 
a TEX file to start at this point. 


To start the processing chain after text formatting, specify /NOTAG— 
TRANSLATOR and /NOTEXT_FORMATTER on the VAX DOCUMENT 
command line to suppress the tag translator and the text formatter. You 
must have a DVI_device file to start at this point. 


To print the output file without reprocessing it, specify /NOTAG— 
TRANSLATOR, /NOTEXT_FORMATTER, and /NODEVICE— 
CONVERTER to suppress the tag translator, the text formatter, and 

the device converter. You must have a device-specific output file, such as 
an .LNO3 file. 
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4.4.2 Processing in Batch Mode (Using /BATCH) 


You can specify a qualifier on the command line that submits your 
DOCUMENT command for processing as a batch job, instead of running it 
interactively (interactive processing occurs by default). By specifying /BATCH 
with the rest of your command line, you can continue processing while your 
terminal is free for other use. Also, by default, the /BATCH qualifier creates a 
log file, with the same file name as the input file and a file type of LOG. The 
log file, which is placed in your current directory, contains a listing of any 
processing errors found by the tag translator or by the text formatter. The log 
file can be typed or edited. 


When processing in batch, there is no need to use the /LIST qualifier if the 
batch log file is printed or kept. 


The /BATCH qualifier accepts many keywords to modify the batch processing 
activity. These keywords are the same as the Digital Command Language 
(DCL) SUBMIT command qualifiers, which are explained in the VAX/VMS 
DCL Dictionary. An example is shown in Appendix A of this manual. 


4.4.3 Printing an Existing File 


Ordinarily, a file is printed automatically when you issue the DOCUMENT 
command, unless you specify the /NOPRINT qualifier or the destination as 
TERMINAL or MAIL on the command line. However, you might want to 
print a file that has been previously processed and printed or one for which 
you previously suppressed printing. In this case, specify that the file does 
not require tag translation, text formatting, or device conversion, by using the 
following qualifiers on the command line: | 


$ DOCUMENT file-spec doctype destination /NOTAG_TRANSLATOR - 
$_/NOTEXT_FORMATTER /NODEVICE_CONVERTER 


Print only those files that were successfully processed through the device 
converter. Use the DOCUMENT command line, specifying the command 
line qualifiers /NOTAG_TRANSALTOR, /NOTEXT_FORMATTER, and 
/NODEVICE_CONVERTER. 


You can use the DCL PRINT command to print files if you want to get a hard 
copy of your input file, including the untranslated code, or if you want a hard 
copy of the LOG or LIS file. You can also use the DCL PRINT command to 
print, with the appropriate qualifiers, any of your final output files, as shown 
in Table 4-2. The queue names are defined by your system manager. 


Table 4—2 DCL Commands for Printing Files 
Type of Output File DCL Command 


LINE, TXT, or TERM $ PRINT filename /QUEUE=queue-name 

LNO3 $ PRINT filename /QUEUE=queue-name /NOFEED 
/PASSALL 

POST $ PRINT filename /QUEUE=queue-name 


/PARAMETER=(DATA_TYPE=POSTSCRIPT) 
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4.4.4 Reprocessing a File for a Different Destination 


Note: 


You cannot reprocess a DVI_device file to make the file readable by a device 
other than the one for which the file was originally processed. The exceptions 
to this rule are files processed for the LINE_PRINTER, TERMINAL, 
and MAIL destinations. These destinations all use the same DVI_LINE 
intermediate file, so you can reprocess for these different destinations. Files 
processed for LNO3_LASER_PRINTER or POSTSCRIPT destinations should 
be sent to a different destination by specifying-the command line: 


$ DOCUMENT file-spec doctype destination 


Or you can reprocess a TEX file (if the TEX file was kept) by skipping the tag 
translation stage: 


$ DOCUMENT file-spec.TEX doctype destination /NOTAG_TRANSLATOR 


The TEX file has already been processed through tag translation, so the 
/NOTAG_TRANSLATOR qualifier specifies that the file should not be 
processed through the tag translator again. 


You cannot reprocess a TEX file using a different doctype than the one 
specified on the original command line. This could cause errors and the 
results are unpredictable. 


4.4.5 Processing or Reprocessing Selected Pages (Using 
/DEVICE_CONVERTER) 


If you want to process and print (or reprocess and print) selected pages of 
a document, you must have kept the DVI_device file. To process selected 
pages, use the /DEVICE_CONVERTER command line qualifier with the 
following keywords: 


e /DEVICE_CONVERTER=STARTING—PAGES=5, which instructs the 
printer to begin printing with page 5 of the document. 


e /DEVICE_CONVERTER=ENDING_PAGE=3, which instructs the printer 
to print pages 1, 2, and 3. 


e /DEVICE_CONVERTER=(start=5, number=3), which instructs the printer 
to print pages 5, 6, and 7. 


Note: When you specify more than one keyword to the /DEVICE— 


CONVERTER qualifier, enclose the keywords in parentheses and 
separate them by a comma. 


Alternately, you can use the following qualifier: 
e /DEVICE=(NUMBER—OF_PAGES=total-pages) is used to specify the 
number of pages to print, when no ENDING_PAGE keyword is specified. 


If both the ENDING_PAGE and NUMBER__OF_PAGES keywords are used 
together on the same command line, VAX DOCUMENT issues an error 
message. 


Refer to Appendix A for more information on these /DEVICE qualifier 
keywords. 
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4.4.6 Altering Page Parameters (Using /DEVICE) 


The /DEVICE=(device-keyword) qualifier contains a useful feature for altering 
the page positioning of an entire document. The following qualifiers shift the 
printed image on the page: 


e /DEVICE=(HORIZONTAL—OFFSET= number-of-points) is used to 
specify the exact text positioning of a document's left margin. The 
HORIZONTAL —OFFSET keyword shifts the image horizontally. 


e = /DEVICE=(VERTICAL _OFFSET=number-of-points) is used to change the 
vertical text positioning. The VERTICAL_OFFSET keyword shifts the 
image vertically. 


In both cases, the number of points is an integer that specifies how far from 
the margin the text should be shifted (72 points is equal to 1 inch). The 
default horizontal and vertical offsets are both 1 inch. 


4.4.7 Including Additional Files (Using /INCLUDE) 


To include an additional file in your final output, specify the /INCLUDE 
qualifier on the DOCUMENT command line. 


The /INCLUDE qualifier specifies that a file is included at the front of your 
output. It assumes an .SDML file type for the included file if none is specified, 
but accepts other file types. 


An example of a file that might be included with the /INCLUDE qualifier is 
a cover page that reads “For Internal Use Only.” The input file that contains 
the cover page text, perhaps called COVERPAGE.SDML, would be specified 
on the command line with /INCLUDE=coverpage. 


Another way to include a file is to use the <INCLUDE> (file-spec) tag. This tag 
serves the same purpose as /INCLUDE, except that the file is included into 
your output file at the exact location of the tag. 


4.4.8 Conditionalizing Files (Using /CONDITION) 


VAX DOCUMENT allows you to conditionalize an input file so that you can 
process the same file to obtain different output for different purposes. The 
/CONDITION qualifier can be used on the DOCUMENT command line to 
establish the condition under which the file is processed. 


For an example of a conditionalized file, consider the following situation: you 
want to write two letters, one to a friend and one to an acquaintance. You 
want most of the text of the two letters to be the same, but you want to add 
a personal note only to your friend. In this case, you actually need to write 
only one letter. 


If the file that contains the letter is called MYLETTER, you can create 
conditional sections in MYLETTER, with <CONDITION> (personal) tags, where 
“personal” is the condition-name. Then, you process this file twice. You 
process the letter to the acquaintance, using the usual DOCUMENT command 
line. You also process the letter to your friend, but this time, you use the 
/CONDITION qualifier on the command line, specifying the condition as 
“personal.” For example: 


$ DOCUMENT myletter LETTER LNO3 /CONDITION=personal 
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4.4.8.1 


4.4.8.2 


When the same condition-name used in the <CONDITION> tag is specified 
on the command line, all text that was tagged with that condition-name 

is included in the output. In this example, all of the text tagged with 
<CONDITION> (Personal) is included. The same text is suppressed when 
the /CONDITION qualifier is not specified on the command line. 


If you have placed <CONDITION> tags in your file, but do not set the 
condition during processing, no error message is generated. In this case, the 
conditionalized text is suppressed. 


Using the <SET_CONDITION> Tag 

You can set a condition by using the <SET_CONDITION> tag. Then, you do 
not use the /CONDITION qualifier when you process the file, but instead set 
the condition in the file, itself, at the top of the file. 


Continuing with the same example, you could place the tag 
<SET_CONDITION> (personal) in a separate SDML file (called FRIEND_ 
NOTES.SDML) and include that file at the beginning of your input 

files MYLETTER.SDML, by using /INCLUDE=FRIEND_NOTES. In 
FRIEND_NOTES, you could also define symbols to be used only when 
Condition=personal is set. You can even include text in that file, so that the 
text is included only when the condition is set. 


There is no distinction between a condition that is set with a /CONDITION 
qualifier on the command line and a condition that is set by a 
<SET_CONDITION> tag in an input file. 


If you set the same condition on both the command line and in the file, no 
error will result. 


Setting More than One Condition 

It is possible to use more than one condition name to create conditional 
sections of an input file. You can tag some text elements with one condition 
name, and other text elements with a different condition name. During 
processing, the conditional text that does not match a set condition is not 
included in the output. 


To set more than one condition in a file, you must use <SET_CONDITION> 
tags on all but one condition, because the /CONDITION qualifier can set 
only one condition. 


For information on using conditions during bookbuilding or related 
processing, see Section 4.6.1. 


4.4.9 Assigning a New Output File Name 


If you choose to process a conditional file twice to get two different output 
files, you may want to use the DCL RENAME command to rename the output 
file to a different name. For example: 


$ DOCUMENT myletter LETTER LNO3 /CONDITION=personal 
$ RENAME myletter.LNO3 friend_letter.LN0O3 


Alternatively, if you wish to store your output file on a device or directory 
other than your current default device and directory, that can be done as 
shown in the following example. 


4.5 


4.5.1 


Bookbuilding 
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$ DOCUMENT myletter LETTER LNO3 /CONDITION=personal 
$ COPY []myletter.1n03 device_name: [directory_spec]myletter.1n03 
$ DELETE []myletter.1n03 


In this example, “device_name” and “directory_spec” refer to the target 
device and directory. 





Besides processing an individual file, you can process a group of files as a 
book. This process is called a bookbuild. The major benefit to processing 
a file as part of a book is that the bookbuild creates a file that contains 
all the symbol names that you have used throughout the book. You can 
subsequently reprocess individual elements of the book using the file of 
symbol names to resolve cross-references to other elements of the book. 


There are three steps to processing a group of input files through a bookbuild: 


1 Create the book element input files, naming them with SDML file types. 
These files can be empty but each file must contain a book element tag, 
and these must have symbol-names. Book elements are discussed in 
Section 4.5.1. 


2 Create a profile, naming this file with an SDML extension also. A profile 
contains a list of <ELEMENT> tags that specify the elements that compose 
your book. Once created, this profile becomes the file that you specify on 
the DOCUMENT command line for processing. 


3 Process the profile. 


Each step in building a book is described in the following sections. 


Creating Input Files 


When the structure of the book is clearly known, create a file for each 
element. All of the text need not be written. Use a <CHAPTER> or 
<APPENDIX> tag to head each element, and add <HEADx> tags if you 
have an outline of the chapter. The actual paragraphs of text can be filled in 
when you come to write the chapter. 


If you have not yet decided on the order of the chapters, or if the order could 
change, name each chapter with a descriptive name (for example, INTRO 
CHAP.SDML) instead of a numbered title (as in CHAP1.SDML). You can 
then easily reorder the chapters without renaming the files that contain them. 


When creating your book element input files, remember the following points: 


e Place each book element in a separate file by placing one of the following 
book element tags in the file as its first tag: 


<APPENDIX> 
<CHAPTER> 
<FRONT_MATTER> 
<GLOSSARY> 
<PART> 
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¢ <A book element file should contain only one of the book element tags. 
' For example, two <CHAPTER> tags should not be placed in one file if 
you want to process that file in a bookbuild. The tag that identifies the 

file as a book element must be the first tag to appear in the file. 


e Each book element tag must contain a symbol-name argument if it will 
be part of a bookbuild. 


e There must be one file for each book element. 


4.5.2 Creating a Profile 
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A profile is an SDML file that contains a list of all of the elements in a book, 
including the front matter, chapters, appendixes and glossary, if any. The 
profile also can contain tags that specify where a table of contents or index 
should be placed in the book and tags that specify logical names for files that 
are included. Only a specific set of tags can be placed in the profile. All valid 
profile tags are listed in Table 4-3. 


Table 4—3 Profile Tags 


Tag Purpose 

<PROFILE> Signals VAX DOCUMENT that the file is a profile 
submitted for a bookbuild. 

<ELEMENT > (file-spec) Identifies the file specification of an element of the 
book. 

<INCLUDES_FILE> (logical- Defines a logical name for the file specification of a 

name\file-spec) file included within the previous book element. See 
Section 4.5.3.2. 

<CONTENTS_FILE> t Specifies the location in the book where a table of 
contents file should be included. 

<INDEX_FILE> f Specifies where an index file should be included in 
the book. 

<COMMENT> t Used to make comments about the elements of 
the profile. 

<ENDPROFILE > Terminates the profile. 





+These tags are also valid in files other than profiles. 





To create a profile that reflects the structure of the book, list (in a separate 
input file) all the files that are part of the book, tagging each file name 

in the list with an <ELEMENT> tag. In the front of the file, place the 
<PROFILE> tag, and at the end of the file, place the <ENDPROFILE> tag. 
Name this SDML file with any name that indicates it is a profile (for example, 
MYBOOK_PRO.SDML). 


Each <ELEMENT> tag should specify a file that contains a book element. An 
example of a profile follows: 


A book named How to Use a Computer has a profile that contains the 
following tags. 
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<COMMENT>(This is the profile of How to Use a Computer) 
<PROFILE> 
<COMMENT>(I want my table of contents to go first:) 
<CONTENTS_FILE> 
<ELEMENT> (Mydisk: [Mydirectory]intro_chap.sdml) 
<ELEMENT> (Mydisk: [Mydirectory]applications_chap.sdm1) 
<ELEMENT> (Mydisk: [Mydirectory]tools_chap.sdm1l) 
<ELEMENT> (Mydisk: [Mydirectory]conclusion_chap.sdml) 
<ELEMENT> (Mydisk: [Mydirectory]questions_app.sdm1l) 
<COMMENT>(I want the index at the end:) 
<INDEX_FILE> 
<ENDPROF ILE> 


Each of the book element files listed in the example must contain a book 
element tag and a symbol name for that element. For example, the chapter 
TOOLS_CHAP.SDML should begin with the following tag: 


<CHAPTER>(Using Basic Computer Tools\comp_tools_chap) 


“Using Basic Computer Tools” is the chapter title and “comp_tools_chap” is 
the symbol name of the chapter. 


4.5.3 Processing a Profile 


4.5.3.1 


To perform a bookbuild, use the following command on the command line: 
$ DOCUMENT profile-spec doctype destination 


Profile-spec specifies the name of the SDML file containing the profile of the 
book being processed. 


VAX DOCUMENT recognizes that it is building a book when it reads the 
<PROFILE> tag in the profile. Processing the profile creates a cross-reference 
(XREF) file for the book. For example, if MYBOOK—PRO.SDML is the profile 
name, typing the following line creates a complete cross-reference file of all 
the symbol-names in the book. The cross-reference file is called MYBOOK— 
PRO.XREF and the final output file (processed for the REPORT doctype) is 
called MYBOOK_PRO.LNO3. 


$ DOCUMENT MYBOOK_PRO REPORT LNO3_LASER_PRINTER /CONTENTS /INDEX 


You might want to process a profile with the /NOPRINT qualifier so that the 
book is not printed by default. You must specify /CONTENTS and /INDEX 
if you want table of contents and index files. 


Listing the Input Files 

A command line qualifier that is useful during a bookbuild is /MAP. This 
qualifier lists all the input files processed by VAX DOCUMENT in one 
separate MAP_LIS file, thereby keeping track of the files included and their 
order. The list starts with the first input file processed and includes any input 
files specified by <ELEMENT> or <INCLUDE> tags. In the list, files that are 
included by other files are indented under those files. 


If you do not specify a file type, the MAP file is given the same name as the 
profile with a file type of MAP_LIS. 


The /MAP qualifier is valid only if tag translation is being done. If 
/NOTAG_TRANSLATOR is specified with the /MAP qualifier, the /MAP 
qualifier is ignored, and VAX DOCUMENT issues an informational message 
stating that you have specified conflicting qualifiers. 
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4.5.3.2 


Defining Logical Names for Included Files 

To define logical names for included files in book elements, use the 
<INCLUDES_FILE> tag in your profile. The <INCLUDES_FILE> equates a 
logical name with a file specification during VAX DOCUMENT execution. 
The tag’s format follows: 


<INCLUDES_FILE> (logical-name\file-spec) 


Place the <INCLUDES_FILE> tag in your profile to define a logical name for 

a file whose contents are included in one of your element files. The first 
argument to <INCLUDES_FILE> is the logical name for the included file. You 
then use this name as the argument to the <INCLUDE> tag in one of the book 
element input files. The second argument specifies the actual file specification 
into which the logical name translates. 


The <INCLUDES_FILE> tag is valid only within a profile. You should place 
it directly after the <ELEMENT> tag that names the book element file that 


includes the input file. During a bookbuild, VAX DOCUMENT establishes 


the logical name definition for each <INCLUDES_FILE> tag before it actually 
reads and processes the element file name in the preceding <ELEMENT> tag. 
The logical name remains defined during the processing of later elements. 


When an element or subelement is processed by itself (when you use 
the /PROFILE qualifier on the command line), VAX DOCUMENT 
again establishes the logical name definitions that were specified by the 
<INCLUDES_FILE> tags in the profile. 


The following example illustrates the use of the <INCLUDES_FILE> tag ina 
profile: 


A writer is drafting a book titled Purebred Dogs. The book contains two 
chapters, one discussing different breeds, and one on the care of purebreds. 
In addition, there is front matter (title page and preface) and an appendix. 


The file identified in éach <ELEMENT> tag corresponds to the exact file-name 
of each book element file. The profile, named CANINE_PRO.SDML, looks 
like this: 


<PROF ILE> 
<ELEMENT> (FRONT . SDML) 
<ELEMENT> (BREEDS . SDML) 
<ELEMENT> (CARE. SDML) 
<ELEMENT> (APPENDIX. SDML) 
<ENDPROF ILE> 


If the book element “CARE.SDML’” itself includes two figures and each figure 
is in a separate SDML file, those figure files could be included by logical- 
names instead of full file specifications. The logical-names could be defined 
right in the profile, as follows: 


<PROF ILE> 
<ELEMENT> (FRONT . SDML) 
<ELEMENT> (BREEDS . SDML) 
<ELEMENT> (CARE. SDML) 
<INCLUDES_FILE>(bassets_fig\mydevice: [mydirectory]dogcare_figi.sdml) 
<INCLUDES_FILE>(beagles_fig\mydevice: [mydirectory]dogcare_fig2.sdml) 
<ELEMENT> (APPENDIX . SDML) 
<ENDPROF ILE> 
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In CARE.SDML, you might have the figures referenced and included as 
follows: 


<P>The following illustration shows all the basset hound breeds of North 
America. 
<INCLUDE> (bassets_fig) 


<P>In comparison, the next figure illustrates the beagle types throughout 
North and South America. 
<INCLUDE> (beagles_fig) 


Notice that the <INCLUDES_FILE> tag in the profile does not actually include 
the figure, but assigns a logical name to the figure file. Refer to the tag 
description in Chapter 9 for an explanation of the tag’s syntax. 


4.5.4 Recovering from Errors 


If any of your book element input files contain enough tag translator errors 
to halt the processor, the tag translator will not produce a .TEX file of 
that element, and the bookbuild will stop after the last element has been 
processed. To fix this, you should take the following steps: 


1 Fix the errors in the book element input files. 


2 Reprocess each revised book element file by typing the following 
command: 


$ DOCUMENT input-file-spec doctype destination /NOTEXT_FORMATTER 
/PROF ILE=profile-spec 


The input-file-spec is the specification of that individual book element file 
and the profile-spec is the specification of the profile. 


3 Submit the bookbuild again, this time using the /NOTAG_ 
TRANSLATOR qualifier to avoid sending the entire book through the 
tag translator for a second time: 


$ DOCUMENT profile-spec doctype destination /NOTAG_TRANSLATOR 


Chapter 5 discusses troubleshooting of errors in more detail. 





4.6 Processing an Element of a Book 


As mentioned in Section 4.1, you can process a book element individually 
by treating it as a stand-alone file and specifying the file name on the | 
DOCUMENT command line. However, any references to symbol names 
outside of that element will not be resolved. 


To process an individual book element and have all its references resolved 
correctly, you must have previously processed the entire book through 

a bookbuild to create an XREF file. Then, to process only one element, 

you can specify the name of the XREF file to the command line, telling 
VAX DOCUMENT where to find the symbol-names to resolve the references 
in the element. The name of the XREF file is specified on the command line 
with the’ /PROFILE qualifier. 


The XREF file has the same name as your profile, but has the file type of 
XREF. 
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To process a book element individually, use the following command on the 
command line: 


$ DOCUMENT input-file-spec doctype destination /PROFILE=profile-spec 


Input-file-spec specifies the input file to be processed. Profile-spec identifies 
the name of the cross-reference file that contains the symbol names of the 
book. 


This command line processes an element of a book and sends it to the 
specified destination. All symbol-name references within the element are 
resolved; however, the page numbering begins with 1. 


Notice that the /PROFILE qualifier is used only to identify the XREF file 
during an element or subelement build. You should not use the /PROFILE 
qualifier when doing a bookbuild because you specify the profile name as the 
file to be processed. 


For more information about referencing symbol names, see Chapter 6. 


4.6.1. Building a Conditionalized Book Element 


When you build a book element after building the whole book with a 
condition set, the condition is automatically set in the element build. This 
happens because the /CONDITION qualifier is stored in the cross-reference 
file during the bookbuild and then re-used. 


If you want to build an element of a conditional book without the condition, 
you need to specifically override the condition during the element build. 

At the time of the element build, use the /CONDITION qualifier on the 
command line, specifying a new condition name. The new condition name 
supplants the original condition for that element. The new condition name 
can be any fictitious name (for example, /CONDITION=FAKE). Since you 
have no <CONDITION> (fake) tags in your book element input file, no text will 
be eliminated from the output file. 





4.7 Processing a Subelement of a Book 
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Note: 


If a book element is long enough to be divided into more than one file, 
creating subelement files, you can process any of those subelements 
individually. To do this, use the following command on the command 
line: 

$ DOCUMENT input-file-spec doctype destination - 

_$ /ELEMENT=file-spec /PROFILE=profile-spec 


input-file-spec specifies the subelement input file to be processed. 


/ELEMENT=file-spec identifies one of the files listed in the profile; the file 
specified in the input-file-spec is a subelement of this element. 


/PROFILE=profile-spec identifies the XREF file containing the book’s symbol 
names. 


This command line processes a subelement of a book and sends it to the 
specified destination. Cross-references within the subelement are resolved 
and a new XREF file is created; however, the page numbering begins with 1.. 


For a subelement build, the book element file and all the other 
subelement files need to be present, because the tag translator reads the 
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whole element and all its included files even though the entire element is 
not included in the output. 


You only need to do a subelement build if one of the following conditions 
exists: 


e The file is included in another file that is listed as an <ELEMENT> ina 
profile. 


¢ The file contains references to symbols defined in other files. 


¢ You want the output file to have the same heading level numbers, table 
and figure numbers, and so on, as if the file were processed with the 
entire element. . 


Heading level numbers, figure numbers, and table numbers, are correct only 
if they have symbol-name arguments. 


You do not need to use a subelement build if you are only processing a file to 
check text content or spelling. In this case, you can process the subelement 
file as a stand-alone file. 





4.8 Simultaneous Element and Bookbuilds 


If two or more users are working on the same book and try to process 
separate elements of the book simultaneously, specifying the /PROFILE 
qualifier to reference the XREF file for the book, the XREF file may not be 
accessible by one of the users and cross-references will not be resolved. 


For example, one user opens the XREF file and loads it into memory 

prior to doing the build on a book element. The tag translator locks the 
existing XREF file, so that no one else can use it until a new XREF has been 
successfully written. The file is locked to ensure that any symbol name _ 
changes introduced by an element build will get incorporated in subsequent 
builds. 


VAX DOCUMENT protects against the use of an old XREF file by locking the 
file. A second user will be unable to open the XREF file. That user receives 
an error message about the XREF file failing to open, and the tag translator 
halts. 


Writers can work independently on separate chapters of a book and can do 
their element builds without concern for the actions of other writers. But 
they should be prepared for an error message from the tag translator if they 
attempt to do an element build at the precise moment that another writer has 
the XREF file locked. 


If you get such a message, wait a minute or two and try the element build 
again. The lock happens only during the first pass of the tag translator, when 
it is reconstructing the XREF file, so even though it may take several minutes 
to completely process a chapter, the actual time that the XREF is locked will 
be less. 


Likewise, when someone starts a bookbuild, and the <PROFILE> tag is 

encountered, any existing XREF file is locked. Therefore, other users cannot 
be doing element builds using this XREF file. If the writer doing an element 
build opens the XREF file right before a bookbuild begins, the bookbuild itself 
will abort. 
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Ff, ~— Troubleshooting SDML Files 


During processing, VAX DOCUMENT diagnoses the source file and checks. 
for errors. Error messages are produced when VAX DOCUMENT encounters 
the following error conditions: 


e¢ Misspelled SDML tags and argument names 
e Tags used out of proper context 
¢ Missing terminating tags 


VAX DOCUMENT issues a message that provides the line number, the 
probable cause, and other information about the error. The user returns to 
the source file to correct the error and reprocess the file. 


However, in some cases, the file processes without producing any error 
messages, but the printed output clearly indicates that something has been 
forgotten or that something needs to be adjusted. A few problems of this 
nature are quite common and examples of incorrect and correct input are 
shown in this chapter. 


If you have a batch process running for an abnormally long amount of time, 
have your system manager check that the system parameters are set correctly, 
including the required space quota amount. 





5.1 Error Messages 


Error messages and informational messages are produced by each of the 
processing programs in the VAX DOCUMENT system: 


e The tag translator 
e The text formatter 


e The device converter 


VAX DOCUMENT messages have the following general format, consisting of 
four fields: 


%FACILITY-S-IDENT, text... 

Facility 

The facility field in the message identifies the program that issues the 
message. 


The VAX DOCUMENT facility prefixes are: 
¢ %DOC 
¢ %TAG 
* %DVC 
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Severity 


The severity field indicates the seriousness of the error. 
e I—The message is informational; processing is not affected. 


¢ W—tThe message provides a warning; processing is not terminated. 
A warning is produced if arguments are supplied where they are not 
necessary, or if a tag has been misspelled, such as <TABLER> . 


If the tag translator generates more than 30 warnings by the time it 
finishes its first pass through a file, it stops processing at the end of 
that pass. You can see the error messages and fix the errors before 
reprocessing the file. 


e E—A major error has occurred; processing continues, but no output may 
be produced. 


e F—The message indicates a fatal problem; processing is terminated. 


Fatal problems, such as missing terminator tags, must be corrected before 
the file can be processed further. 


Identification 
The identification field is an abbreviation of the problem found by the 
processing program. 


Text 
The text of the message, if present, describes the problem found by the 
processing program. The following error message is an example of the 
message format: 
%.TAG-W-GTMAXARGS at tag <P> on line 1 in file 

disk: [directory] filename .SDML 

More than O arguments supplied to tag <P> 
%TAG-W-GTMAXARGS 


The facility, severity, and identification of the message. This warning message 
was issued by the tag translator. 


at tag <P> online 1 in file 
The first line of text provides the line number and the name of the tag being 
evaluated when the message was issued. 


disk:[directory]filename.SDML 
The second line of text provides the name of the file being read. 


More than O arguments supplied to tag <P> 
The third line identifies the problem. 


If VAX DOCUMENT is running interactively, error messages from the tag 
translator are displayed on the screen and recorded in a LIS file if the /LIST 
qualifier is used. The LIS file has the same name as the source file, with the 
LIS file extension. Error messages from the text formatter are written to a LIS 
file. 


If VAX DOCUMENT is running in batch mode, error messages are 
automatically written to a LOG file. 
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5.2 Output Problems 


Sometimes processing completes without an error, but when the output is 
printed, it is easy to see that things have somehow gone awry. 


This section illustrates some common solutions to problems that a writer must 
diagnose after seeing the formatted output. 


5.2.1. Incorrect Paragraph Indentation 


A common mistake when coding a file is to leave out <P> tags. Most often, 
the tags are left out after major headings, such as chapter titles and headings. 


The problem is only apparent in doctypes that place headings at a different 
margin than paragraphs. 


Incorrect Input 


<CHAPTER> (symbol-name) 
Paragraph text... 


<HEAD1i>(First-level Heading) 
The information in this chapter covers... 


<P>Also including is... 


<HEAD2>(Second-level Heading) 
First item under discussion. 


<P>Details... 


Correct Input 

<CHAPTER> (symbol-name) 

<P>Paragraph text... 

<HEAD1>(First-level Heading) 

<P>The information in this chapter covers... 
<P>Also including is... 

<HEAD2>(Second-level Heading) 

<P>First item under discussion. 


<P>Details... 


5.2.2 Problems with Examples 


Code examples, interactive examples, and syntax examples appear on the 
printed page as monospaced output. Because of the change to a monospaced 
font, examples restrict the use of many tags. Tags that require special 

text formatting, such as lists, tables, and headings, cannot be used within 
monospaced examples, nor may index tags be used. 


When the <CODE_EXAMPLE> tag is used with the <ENDCODE—EXAMPLE> 
tag, spacing is preserved. However, when the <CODE_EXAMPLE> tag is used 
with an argument and no terminating tag, any leading or trailing spaces are 
not preserved. 


5-3 


Troubleshooting SDML Files 


Incorrect Input 


<TABLE> 
<TABLE_SETUP> (2\10) 
<TABLE_HEADS> (Variable\Value) 
<TABLE_ROW> (<CODE_EXAMPLE> (ABC) \<CODE_EXAMPLE>( 1)) 
<TABLE_ROW> (<CODE_EXAMPLE> (XYZ) \<CODE_EXAMPLE> (100) ) 
<ENDTABLE> 


Correct Input 


In this example, the writer was trying to use the spaces to align the values in 
the table. The <ALIGN_CHAR> tag produces correct alignment: 


<ALIGN_CHAR> (#) 

<TABLE> 

<TABLE_SETUP> (2\10) 

<TABLE_HEADS> (Variable\Value) 
<TABLE_ROW> (<CODE_EXAMPLE> (ABC) \<CODE_EXAMPLE> (##1) ) 
<TABLE_ROW> (<CODE_EXAMPLE> (XYZ) \<CODE_EXAMPLE> (100) ) 

<ENDTABLE> 

<ENDALIGN_CHAR> 


5.2.3 Incorrect Sequencing of Formal Elements 
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Formal elements can be output out of sequence if coded inconsistently. 

For example, it is possible to code three figures that the tag translator 
automatically numbers 1, 2, and 3. In the output, the figures could possibly 
appear out of sequence, for example, as 2, 1 and 3. 


The problem arises if the figures are coded with the FLOAT attribute. After 
the tag translator numbers the figures, it is possible for the text formatter to 
float them out of order. 


Incorrect Input 


<FIGURE>(Caption\symbol1) 
<FIGURE_ATTRIBUTES> (FLOAT) 
<FIGURE_SPACE> (10) 

<ENDF IGURE> 


<FIGURE> (Caption\symbo12) 
<FIGURE_ATTRIBUTES> (FLOAT) 
<FIGURE_SPACE> (10) 

<ENDF IGURE> 


<FIGURE>(Caption\symbol13) 
<FIGURE_ATTRIBUTES> (FLOAT) 
<FIGURE_SPACE> (10) 

<ENDF IGURE> 


If all three figures are short, any of the figures could float out of order. To 
correct this problem, code all three figures with the KEEP attribute. 


Correct Input 


<FIGURE> (Caption\symbol1) 
<FIGURE_ATTRIBUTES> (KEEP) 


<FIGURE> (Caption\symbol2) 
<FIGURE_ATTRIBUTES> (KEEP) 


<FIGURE> (Caption\symbo13) 
<FIGURE_ATTRIBUTES> (KEEP) 
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6 _sReferencing Symbol-Names 


VAX DOCUMENT allows you to create and reference symbol-names for any 
type of information that is subject to change. This ensures that documents 
are always up to date, especially in regard to the following references: 


e References to text elements that might change, such as the name of a 
product or project. 


e References to book elements that have numbers associated with them, 
such as chapters. 


This chapter describes how to create symbol-names for text and book 
elements and how to reference them. 


A symbol-name is a term that you assign to some text which, once created, 
becomes an easy and reliable way to refer to past or future chapters, tables in 
other sections of the book, figures, other writers’ books, and numerous other 
references. 


6.1 Creating Symbol-Name 


You can create symbol-names for both text elements and book elements. 
Each symbol-name is assigned as a tag argument. For example, to assign a 
symbol-name to an example captioned VAXcluster Multi-file Summary, you 
could put the following tag into your SDML file: 





<EXAMPLE>(VAXcluster Multi-file Summary\multi_file_exam) 


The symbol-name multi_file_exam could then be referenced anywhere in the 
document, with the <REFERENCE> tag: 


ae <REFERENCE> (multi_file_exam) 


When VAX DOCUMENT processes the <REFERENCE> tag, it substitutes the 
actual name for the symbol-name in your output. In this case the symbol- 
name “multi_file_exam” would be replaced with “VAXcluster Multi-file 
Summary.” 


Symbol-names must not exceed 31 characters, and can consist only of 
alphabetic letters, numbers, and underscores. Do not begin a symbol-name 
with an underscore. 


The following naming convention might be useful: in each symbol-name, 
suffix the name with the type of text element for which you are creating a 
symbol. For example, a symbol-name for a table might be called “american 
kings_tab,” or for a chapter, “american—_kings—chap.” This convention makes 
it easy to identify different types of symbol names as you edit a source file. 
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6.2 Storing Symbol-Names in a Cross-Reference File 


Note: 


An automatic function of VAX DOCUMENT is to create a cross-reference 
file, which is a file containing a list of the symbol-names used in one or 
more files. An entry in the cross-reference file may have some or all of the 
following information associated with it: 


¢ The symbol-name. As previously described, symbol-names must be no 
more than 31 characters in length, and must have only alphabetic letters, 
numbers, or underscores in them. 


¢ A symbol-type. Each cross-reference file entry must have a symbol-type, 
which not only indicates the type of element to which a symbol refers 
(for example, Figure, Table, or Chapter), but may also control the output 
when the symbol is referenced. For example, if the element is a Chapter 
type, the output associated with the reference to it is the default text 
“Chapter.” 


¢ A symbol-value. Cross-reference file entries for text elements that have 
numeric values associated with them (header levels, figures, numbered 
tables, and so on) always associate this number with the symbol-value. 


¢ The symbol-text. The text associated with a cross-reference file entry is the 
text string associated with it: the chapter title, a figure caption, heading 
level text, or a user-defined string. 


When you process an individual file that contains symbol-names, those 
symbol-names are temporarily placed in the cross-reference file (in your 
computer system’s memory). VAX DOCUMENT uses the table to resolve all 
symbol-name references, then erases the table from memory. 


When you process a book through a book build, or an element of a book 
through an element build, VAX DOCUMENT again creates a cross-reference 
file and uses it to resolve all references. However, the book building process 
requires that the symbol-names be stored for later use, so VAX DOCUMENT 
saves the cross-reference file by copying it into the directory that contains the 
profile used to perform the book build. This copied file is named with the 
profile name and is given the filetype of XREF. 


The XREF file is not readable; you should never attempt to edit it. Also, 
do not delete it; if it is deleted accidentally, you must perform a new book 


build.before any subsequent element builds can be done. 


6.3 Creating Symbol-Names for Text and Book Elements 


6-2 


Text and book elements can be divided into two groups, sequenced and 
nonsequenced elements. 


A sequenced element is labeled in the output. The number or letter assigned 
is relative to the other elements of the same type in the rest of the book. For 
example, a table is assigned the number three only if there are two tables 


“before it in the book element being processed. 


The following tags mark sequenced elements and are used to create symbol- 
names for these elements: 


: <APPENDIX> 


° <CHAPTER> 
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° <EXAMPLE> 
° <HEADx> 

bd <FIGURE> 

bd <PART> 


be <TABLE> 


A nonsequenced element is any text string or book element that does not 
need to be numbered. An often used sentence or statement is an example of 
a nonsequenced text string. A book title is also a nonsequenced text element, 
as it does not receive a number. 


The following tags are used to create symbol-names for nonsequenced text 
elements: 


7 <DEFINE_BOOK_NAME> 
nf <DEFINE_SYMBOL> 
© <FRONT_MATTER> 


© <GLOSSARY> 


See Chapter 9 for full descriptions of these tags. 


The <DEFINE-SYMBOL> and <DEFINE_BOOK_NAME> tags accept a symbol- 
name as their first arguments. The book element tag <FRONT_MATTER> 
accepts a symbol-name as its only argument. For all other tags that accept 
symbol-names, assign the symbol-name as the tag’s second argument. 


Each book element requires a symbol-name if the book is to be processed 
through a bookbuild; if you use these tags without symbol-name arguments, 
no entry is added to the cross-reference file during processing and you receive 
a warning message. 


For example, a chapter might have its title and symbol-name identified as 
follows: 


<CHAPTER>(Running the Program\ref_chap) 


The <CHAPTER> tag creates a cross-reference file entry for this chapter. The 
chapter’s symbol-name is saved in the table as ref_chap. Other information 
associated with this symbol is also saved, including the chapter title, Running 
the Program, and the chapter number (which is assigned automatically). This 
chapter’s symbol-name, which appears in the <CHAPTER> tag argument 

at the head of the book element, becomes the key to element building, as 
described in Section 4.6 of Chapter 4. 


6-3 
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6.4 Referencing Text and Book Element Symbol-Names 


The <REFERENCE> tag is used to reference any kind of symbol-name. 
The first argument to this tag is always the symbol-name you want to 
reference. Any symbol-name specified by the <REFERENCE> tag causes 
the tag translator to search the cross-reference file for the definition of the 
symbol-name and to replace the reference with the definition. For example: 


See <REFERENCE>(ref_chap) for step-by-step instructions. 


This book element reference causes the tag translator to look in the cross- 
reference file for the symbol-name ref_chap and to replace the tag and 
argument with the default symbol type keyword associated with the chapter 
(for example, “Chapter”) and the chapter number. Therefore, if the preceding 


_ example referenced the third chapter of a book, the output would be as 


follows: 
See Chapter 3 for step-by-step instructions. 


In your source file, the reference to a symbol-name can precede or follow the 
tag that defines the symbol-name, Therefore, the following line: 


<Define_Symbol>(plan_tab\The 43rd Project Plan) 
could be placed anywhere in the document, before or after the following line: 
<p>The series of steps are identified in <reference>(plan_tab) . 


Relative placement of the two tags is unimportant because the tag translator 
makes two passes over a document during processing, creating the cross- 
reference file during its first pass and not using the file to resolve the 
references until the second pass. Therefore, the correct symbol-names are 
always entered in the file before the references are translated. 


6.4.1 Controlling the Output of a Reference 


The <REFERENCE> tag allows you to control the output of a reference 
through use of its second argument. You can use this argument to specify 
that you want either a portion of your reference or the entire reference placed 
in your output. 


Optional second arguments to <REFERENCE> include the following: 


e VALUE—specifies that, if a symbol-name has a value associated with 
it, you want only that symbol-value (number or letter) included in the 
output. 


e TEXT—specifies that you want only the text of a symbol included in the 
output (for example, a chapter title or table caption). 


e FULL—specifies that you want both the value and the text included in 
the output. 


Consider the earlier example of the <CHAPTER> tag, for example, 


VAX DOCUMENT automatically assigns to the book element symbol-name 
its symbol-type keyword, “Chapter,” and its symbol-value, the sequential 
number of the chapter during processing. By default, both the symbol- 
type keyword and the symbol-value are used to replace the symbol-name 
reference. However, if you want the output to include the associated text 
of the symbol-name with the symbol-type keyword and value, you need to 
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specify \FULL in the reference. If “Running the Program” is the title of the 
fourth chapter, and you want that title to be included in your reference, you 
would use the \FULL argument. For example: 


<reference>(ref_chap\FULL) 
Such a reference would automatically output the following text: 
Chapter 4, Running the Program 


When you do not specify a second argument, the output defaults according to 
the symbol-type. Table 6-1 summarizes the default output for each type of 
text or book element. 


Table 6—1 Element Types and Default Output of Symbol-Names 


Text Element 
EXAMPLE 


FIGURE 
HEADx 
TABLE 

BOOK TITLE 
TEXT STRING 


Book Elements 
APPENDIX 
CHAPTER 

PART 

SECTION 

FRONT MATTER 
GLOSSARY 


Second Argument to <REFERENCE> 


(null) VALUE TEXT FULL 

“Example” number caption “Example” number, caption 
number 

“Figure” number number caption “Figure” number, caption 
“Section” number number caption “Section” number, caption 
“Table” number number caption “Table” number, caption 


The title argument specified in <DEFINE_BOOK_NAME> . 
The text-string argument specified in <DEFINE_SYMBOL>. | 


(null) VALUE TEXT FULL 


“Appendix” letter —_ letter title “Appendix” letter, title 
“Chapter” number number title “Chapter” number, title 
“Part” number number title “Part” number, title 
“Section” number number ‘title “Section” number, title 
none none none none 

none none none none 


Here is an example of a figure reference with a defaulted second argument: 


<P><reference>(keyboard_fig) shows the keypad layout. 


<FIGURE>(The Default Keys\keyboard_fig) 
<FIGURE_SPACE> (20) 
<ENDF IGURE> 


In this example, the figure titled The Default Keys was assigned the symbol- 
name of keyboard_fig in the tag <FIGURE>. The reference to this symbol- 
name does not contain a second argument, which means the writer accepts 
the default output. Therefore, if this reference and figure were to occur 

in a chapter numbered three, and would be the fourth formal figure, the 
paragraph containing the reference would have the following output: 


Figure 3-4 shows the keypad layout. 
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If the second argument to the <REFERENCE> tag was \FULL, the output 
would be as follows: 


Figure 3-4, The Default Keys shows the keypad layout. 


6.4.2 Referencing Symbol-Names in Other Files 


For text strings that you reference frequently in separate files of the same 
book, it is useful to place all of your <DEFINE_SYMBOL> and <DEFINE_ 
BOOK_NAME> tags in one file, in a symbol definitions file. Then, to reference 
the symbol-names stored there, specify the name of the symbol definition file 
with the /SYMBOLS qualifier on the DOCUMENT command line when you 
process the file. 


For example, you could create a symbol definitions file named INTRO_ 
BOOK_SYMS.SDML. This file might contain the following symbol-names: 


<define_symbol>(PROGRAM_NAME\Matrix Maker) 
<define_symbol>(PROGRAM_VERSION\3. 2) 


When processing a file that references either of these symbols, you would 
specify the name of the symbol definitions file on the DOCUMENT command 
by typing the following line: 


$ DOCUMENT filename doctype destination /SYMBOLS=INTRO_BOOK_SYMS 


The /SYMBOLS qualifier assumes a filetype of SDML by default. 





6.5 Creating a Preliminary Profile 


Before you write your book, use the following procedure to make sure that 
your symbol-names will be referenced correctly in the entire book or in 
individual elements of the book. If you follow this procedure before you 
begin to write, your symbol-name references will be correct throughout the 
writing process. 


1 When the structure of the book is clearly defined, create a file for each 
element. All of the text need not be written. Use the <CHAPTER> or 
<APPENDIX> tags to head each element, and add <HEADx> tags if you 
have an outline of the chapter. The actual paragraphs of text can be filled 
in when you write the chapter. 


2 Create a profile that reflects the structure of the book. To do this, in a 
separate SDML file, list all the files that are part of the book, tagging 
each file name in the list with an <ELEMENT> tag. In the front of the 
file, include the <PROFILE> tag, and at the end of the file, add the 
<ENDPROFILE> tag. Name this SDML file with any name that indicates 
it is a profile, for example, MYBOOK_PRO.SDML. 


Each <ELEMENT> tag should specify a file that contains a book element. 
No other files should be included in the profile. 


3 Process the profile to create the cross-reference file for the book. Indicate 
that you want to build the book by specifying the profile as the filename 
in the DOCUMENT command line. In this case, MYBOOK_PRO.SDML 
is the name of the profile. 


$ DOCUMENT MYBOOK_PRO doctype destination 
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After completing this procedure, you have a complete cross-reference table of 
all your book element symbol-names. 





6.6 Adding New Symbol-Names 


As you write, you will probably add or delete tags that supply symbol-names. 
To reference new symbol-names and have each reference resolved correctly, 
you must rebuild the affected book elements as you go. You might want to 
rebuild any of the following: 


e An entire book (through a book build) 
e An individual book element (through an element build) 


e¢ A portion of a book element (through a subelement build) 
See Chapter 4 for the procedures for reprocessing files. 


Rebuilding an Entire Book 


You need to reprocess the entire book through a bookbuild only when you 
change the book in either of the following ways: 


e Reorder book elements that have incremental values associated with 
them, for example, reorder the chapters of the book 


e Add additional book elements that affect the numbering of other 
elements, for example, insert a new chapter 


Rebuilding an Individual Element of a Book 


To rebuild a file that contains one element of a book, use the /PROFILE 
qualifier on the DOCUMENT command line. The /PROFILE qualifier causes 
the tag translator to rebuild the cross-reference file with the newest symbol- 
names for that element. 


Rebuilding a Subelement of a Book 


Some books contain a large single element. The element might not be 
subdivided into chapters or appendixes, but instead consists of many 

pages of a highly structured reference section. Each item described in the 
reference section could be written as a separate SDML file, and it becomes 
convenient to process these files individually. In essence, you want to process 
a subelement of a book. 


To process a subelement, two qualifiers are added to the command line, 
/PROFILE and /ELEMENT. The tag translator processes the entire element 
through its first pass to correctly update the cross-reference file, but produces 
output only for the subelement that you specify as the input file on the 
DOCUMENT command line. 


7.1 





Generating a Table of Contents, Index, and Master 


Index 


This chapter describes how to create a table of contents, an index and a 
master index for your document. Complete reference information on the tags 
described in this chapter can be found in Chapter 9. 





Creating a Table of Contents 


You create a table of contents by specifying the /CONTENTS qualifer when 
you process your SDML file. VAX DOCUMENT automatically generates a 
table of contents entry for each of the following in your SDML file: 


e¢ Appendixes, chapters, glossaries, indexes, parts, and prefaces 


¢ Formal examples, figures, and tables (if specified with a caption or a 
symbol-name argument) 


¢ Numbered heading tags (table of contents entries for the <HEAD5> and 
<HEAD6> tags are doctype-dependent) 


¢ SOFTWARE doctype reference-element tags: <COMMAND>, 
<ROUTINE> , <SDML_TAG>, <STATEMENT> , and <FUNCTION> 


¢ SOFTWARE doctype subcommand tags: <SUBCOMMAND> and 
<SUBCOMMAND_SECTION_HEAD> 


e REPORT doctype <SECTION> tag 


See the table of contents in this manual for a sample of a table of contents 
created by VAX DOCUMENT. 


The table of contents is created during the text formatting of your document. 
If you omit text formatting by using the /NOTEXT_FORMATTER qualifier, 
contents generation is also omitted. If you use the /CONTENTS and 
/NOTEXT_FORMATTER qualifiers together, VAX DOCUMENT issues an 
error message. 


VAX DOCUMENT creates a separate file for the table of contents. It names 
this file by taking the file name of the input-file-spec parameter you specify 
on the DOCUMENT command line and appending “CONTENTS” to it. 
You need do nothing more than specify /CONTENTS on the command line 
if you want to maintain your table of contents in a separate file; however, 
if you want this file automatically incorporated in your document, use the 
<CONTENTS_FILE> tag in your SDML file. 


When the <CONTENTS_FILE> tag is processed by VAX DOCUMENT, 

the latest table of contents file is incorporated into the final output file 
where the <CONTENTS_FILE> tag occurs in the SDML file. If you use the 
/NODEVICE_CONVERTER qualifier, the table of contents will not be 
incorporated into your file. 


Generating a Table of Contents, Index, and Master Index 


You can make sure that the latest version of the table of contents is 
incorporated into your file by specifying the /CONTENTS qualifier whenever 
you process a file that contains the <CONTENTS_FILE> tag. This action 
guarantees that the table of contents file correctly reflects the organization 
and pagination of your SDML file. If you do not specify /CONTENTS, an 
out of date table of contents may be included in your document. 


When you create a table of contents using the /CONTENTS qualifier, 
whatever parameters and other qualifiers you specify affect the processing 
of both the table of contents file and your SDML file. For example, if 
the LNO03_LASER_PRINTER destination and the /NOPRINT qualifier 
are specified, both files are formatted for the LNO3 laser printer 
(input-filename.LN03 and input-filename_CONTENTS.LNO3) but neither 
is printed. 


The following example shows how a table of contents may be created along 
with the output of the file MYREPORT.SDML: 


$ DOCUMENT myreport REPORT LNO3 /CONTENTS 


The table of contents generated by the previous command would be 
MYREPORT_CONTENTS.LNO3. 





7.2 Creating an 


Index 


You can automatically generate an index file from your SDML file by using 
the /INDEX qualifier to the DOCUMENT command. To create an index 
using VAX DOCUMENT, you mark the text elements within your SDML file 
that you want included in your index with <x> and <yY> tags, and then 
you process your SDML file using the /INDEX qualifier to generate an index 
file from your SDML file. 


<X> tags are used to create main entries in the index. Main entries have 
page numbers associated with them. <yY> tags are used to create cross- 
reference entries in the index. Cross-reference entries (also called “See” or 
“See also” entries) do not have page numbers associated with them, instead 
they refer:the reader to a main entry in the index. 


Both <x>‘and <y> tags can have subentries (also called subheadings or 
modifications), which are index entries that are indented under either a main 
entry created using the <x> tag, or a cross-reference created using the <yY> 
tag. 


The following example shows a part of an SDML file that contains <x> and 
<Y> tags. The <XSUBENTRY> tag is used to create subentries in both tags. 


<head1>(Usage of Official Vehicles) 

<X>(Vehicles<XSUBENTRY>usage of) 

<Y>(CORP-AUTO report<XSUBENTRY>See Vehicles) 

<p> 

Official vehicle usage is listed in a separate report CORP-AUTO-1439u2. 
This report is organized as in the following outline. 


If these tags occurred on page 3-1, they would create the following index 
entries (under the headings “-C-” and “-V~-”, respectively): 


CORi-_AUTO 
See Vehicles 
Vehicles 


usage of, 3-1 
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See the index in this manual for an example of an index produced using 
VAX DOCUMENT. 


The following example shows a command line that will create an index file 
along with the output of the file MYREPORT.SDML: 


$ DOCUMENT myreport.sdml REPORT LNO3 /INDEX 


You can tailor your index in several ways by using the arguments 
and keywords explained later in this chapter, or you can accept the 
VAX DOCUMENT default index file characteristics. The following list 
describes the default characteristics of an index file: 


¢ Capitalization of index entries is retained in the index as entered. 


e Index entries are formatted in two columns on each page. On the last 
page the entries are balanced so that the two columns are of equal length. 


e¢ Guide headings are automatically inserted into the index before each 
entry that begins a new alphabetic section. For example, when the 
first index entry beginning with the letter “B” is encountered, the guide 
heading “-B-” is placed before it. The exact format of the guide heading 
is doctype-dependent. 


e Index entries are sorted in the index according to the following default 
rules: 


— Entries with all nonalphabetic characters are placed before all other 
entries. 


— Entries beginning with nonalphabetic characters are sorted by the 
alphabetic characters following the nonalphabetic characters. 


— Entries are sorted on a word-by-word basis in which spaces and 
hyphens are treated as significant sorting characters. 


— Index entries generated by the <yY> tag are placed at the beginning 
of each subentry level. This is done on the assumption that cross- 
reference information should be positioned at the top of each 
subentry level so that the user can find it easily. 


e Index entries are merged only when they have identical spelling, spacing, 
emphasis, and capitalization in the SDML file. Page-number references 
are merged only if they refer to the same page and are specified with 
identical attributes such as emphasis and appended text. Even if index 
entries or page numbers look identical on the printed page, they will not 
be merged unless they are coded identically in the SDML file. 


For example, the entries <X> (<TAG> (LINE)) and 

<X> (<TAG> (line)) would appear the same on the printed page 
because the <TAG> tag would format both tag-names in uppercase 
characters. However, these entries would create separate index entries 
because the tag-name is not capitalized consistently in the SDML code for 
both entries. 
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e Either a bullet (e) or a comma (,) is placed between each index entry and 


its first page reference. The character used for punctuation is doctype- 
dependent. For example, if the doctype specifies that commas are to be 
used, the entry appears as follows: 


Command qualifiers, 4-10 


If a main level index entry is followed by a subentry rather than a page 
reference, no punctuation is placed after the main entry. Instead, the 
punctuation is placed after the subentry to set off the page reference as in 
the following example: 


Command qualifiers 


description, 4-10 
examples, 4-12 


7.2.1. Creating Main Index Entries 


Use the <X> tag to create a main index entry. The <x> tag places an entry 
in the index that contains the page number of the output page on which this 
tag occurs. For example, if the <x> tag in your SDML file is processed while 
page 2-132 is being created by the text formatter, the index entry from that 
<x> tag would reference page 2-132. 


The <x> tag has the following syntax: 


<X> (index-entry[\attribute]) 


Use the index-entry argument to supply the text for the main entry and 
subentries in the index. The text used in this argument is placed in the index 
entry exactly as entered, including any capitalization. Use the <XSUBENTRY> 
tag within this argument to separate the main entry from the first subentry, 
and the second subentry from the first, as follows: 


<X> (Main entry <XSUBENTRY> subentry-1 <XSUBENTRY> subentry-2) 


The <XSUBENTRY> tag can be abbreviated as <xS>. You can use no more 
than three subentries in an index. 


Use the attribute arguments to control the sorting and formatting of the 
index entry. You can specify up to five attribute arguments to the <X> tag. 
Section 7.2.2 describes the indexing tag attributes. 


Use the following <x> tag coding rules to ensure that the page references in 
your main index entries are correct: 


e Place <x> tags after tags in your SDML file that are likely to begin a 
new page, such as <CHAPTER> or <HEAD1>. 


e Index entries that are to be merged in the index should be coded 
identically in the SDML file, including emphasis, capitalization, spacing 
and spelling. 


¢ When inserting <X> tags into tables, place the <X> tags within the 
arguments to the <TABLE_ROW> tag, so that the page references will be 
correct if the text formatter breaks the table across pages. | 
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¢ Do not place <x> tags within examples. Doing so may interfere with 
the formatting of the examples. 


The following example shows the correct positioning of the <x> tag that 
provides an indexing entry for a chapter: 

<CHAPTER> (Creating Routines\creating_routine_sec) 
<X>(Routines<XSUBENTRY>creation of) 

<P> . 

In order to create a routine, you must first 


If the previous text appeared on page 11-2, this <x> tag would create the 
following index entry: 


Routines 


creation of, 11-2 


7.2.2 Using Indexing Tag Attributes 


7.2.2.1 


The attribute arguments to the <x> and <yY> tags control the sorting 

and formatting of individual index entries. These attributes are described 
alphabetically in the following sections. All of these attributes can be used 
with the <Xx> tag; however, only the MASTER and <XSORT> attributes can 
be used with the <y> tag. 


Using the BEGIN and END Attributes 

Use the BEGIN and END attributes to create an index entry for consecutive 
pages. These attributes create an index entry with a page range such as 
“System Concepts, 12-3 to 12-7.” When you use a BEGIN and END pair, 
the index entries and indexing attributes you specify must be identical for the 
index entries to be sorted correctly. 


The following example shows how a page range can be coded using the 

BEGIN and END attributes. In this example, the tag with the BEGIN attribute 
is processed on page 12-3 and the tag with the END attribute is processed on 
page 12-7. 


<HEAD1>(Concepts of the System\sys_con) 
<X> (System Concepts\BEGIN) 
<P> 


<X>(System Concepts\END) 
<HEAD1>(Using the System\sys_using) 


These index tags would create a page range as follows: 


System Concepts, 12-3 to 12-7 


If additional entries occur within a BEGIN and END pair, they are ignored, 
and VAX DOCUMENT issues an informational message when it creates the 
index. 
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7.2.2.2 


7.2.2.3 


7.2.2.4 


Using the BOLD Attribute 

Use the BOLD attribute to cause page numbers to appear in bold type in your 
index. If both the BOLD and ITALIC attributes are specified, the page number 
will be output in bold italic type. 


Page number references that are output in a bold type face using the BOLD 

attribute are sorted as being distinct from page number references that are 

output in a bold type face using some other means (such as the global 
<EMPHASIS> ( \BOLD) tag). 


The following is an example of an <X> tag that uses the BOLD attribute: 
<X> (System Concepts\BOLD) 


If this index tag occurred on page 12-3, it would create an entry in the index 
as follows: 


System Concepts, 12-3 


Using the ITALIC Attribute 

Use the ITALIC attribute to cause page numbers to appear in italic type in 
your index. If both BOLD and ITALIC are specified, the page number will be 
output in bold italic type. 


Page number references that are output in an italic type face using the ITALIC 
attribute are sorted as being distinct from page number references that are 
output in an italic type face using some other means (such as the global 
<EMPHASIS> tag). 


The following is an example of an <X> tag that uses the ITALIC attribute: 
<X>(System Formats\ITALIC) 


If this index tag occurred on page 6-11, it would create an entry in the index 
as follows: 


System Concepts, 6-11 


Using the MASTER Attribute 

Use the MASTER attribute to specify that an index entry appear in a master 
index. By default, an entry appears in the master index only if this attribute 
has been specified. 


You can override this default at run-time and have all index entries (those 
labeled with the MASTER attribute and those that are not so labeled) 
placed in the master index when it is created. You do this by specifying 
/INDEX=(OVERRIDE_MASTER) on the DOCUMENT command line. 


See Section 7.2.5 for more information on the OVERRIDE_MASTER 
keyword. See Section 7.3 for information on creating a master index. 
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7.2.2.5 Using the <XAPPEND> Attribute 
Use the <XAPPEND> attribute to append a specified string to the end of a 
main entry page reference. You append the string by passing that string as 
an argument to the <XAPPEND> attribute as <XAPPEND> (string). use the 
<XAPPEND> attribute to add information to a main index entry, for example 
to mark an index page as referring to a table (9-8tab) or to insert common 
indexing terms such as “page 3ff” or “5-3 to 5-6 passim.” 


The following example shows an <X> tag that appends the string “ff” to the 
page reference using the <XAPPEND> attribute: 


<X>(File structure\<XAPPEND>(ff)) 


If this tag were processed on page 3, this tag would create the following main 
index entry: 


File structure, 3ff 


7.2.2.6 Using the <xSORT> Attribute 
Use the <XSORT> attribute to control the default sorting of individual index 
entries. For example, if you wanted the entry “$$” to appear in your index 
sorted as the words “double dollar,” you could place the <XSORT> tag in 
your SDML file as follows: 


<X>($$\<XSORT>(double dollar) ) 


In the previous example, the entry “$$” would be sorted by the string passed 
to the <XSORT> attribute, in this case, “double dollar.” This attribute is 
especially useful for overriding the default sorting of leading nonalphabetic 
characters in individual index entries. 


7.2.3 Creating Cross-Reference Index Entries 


The <yY> tag creates an entry in an index file that has no output page 
associated with it. This tag is typically used to create cross-references to other 
index entries (“See” or “See also” entries). The <y> tag has the following 
syntax: 


<Y> (index-entry[\attribute}) 


The <yY> tag accepts the same index-entry argument as the <X> tag. Index 
subentries are specified within the index-entry using the <XSUBENTRY> (or 
the <xS> ) tag just as for the <x> tag. The <yY> tag accepts only the 
MASTER and <xSORT> indexing tag attributes because all other attributes 
are for manipulating page numbers. 


MASTER indicates that the index entry should only occur in the master index 
and <XSORT> lets you override the sorting algorithm for an individual entry. 
See Section 7.2.1 for more information on these attibutes. Section 7.2.2 
describes the indexing tag attributes. 


The following example shows the <Y> tag used with the <x> tag. The 
<X> tag creates an index entry with a page number reference and the <Y> 
tag creates a “See also” index entry: 


<X>(File structure designators) 
<Y>(File structure designators<XSUBENTRY>See also Header blocks) 
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These indexing tags create the following index entry (assuming these tags 
appeared on page 1-3): 


File stucture designators, 1-3 
See aiso Header blocks 


7.2.4 Processing an Index 


When you use the DOCUMENT /INDEX qualifier, VAX DOCUMENT 
processes the index entries you created in your SDML file, and places them 
in a separate index file. VAX DOCUMENT names this file by taking the 
file name of the input-file-spec parameter you specified on the DOCUMENT 
command line and appending “_INDEX” to it. 


If you omit text formatting by using the /NOTEXT_FORMATTER qualifier, 
index processing will also be omitted, because the index is processed during 
text formatting. If you use the /INDEX and /NOTEXT_FORMATTER . 
qualifiers together, VAX DOCUMENT issues an error message. 


You need do nothing more than specify /INDEX on the command line if you 
want to maintain your index in a separate file; however, if you want this file 
automatically incorporated into your document, place the <INDEX_FILE> tag 
in your SDML file. 


When the <INDEX_FILE> tag is processed by VAX DOCUMENT, the latest 
index file is incorporated into the final output file where the <INDEX_FILE> 
tag occurs in the SDML file. If you use the /NODEVICE_CONVERTER 
qualifier, the index will not be incorporated into your file. 


Use the /INDEX qualifier whenever you process a file that contains the 
<INDEX_FILE> tag to make sure that the latest version of the index is 
incorporated into your file. This action ensures that the index file correctly 
reflects the organization and pagination of your SDML file. If you do not 
specify /INDEX, an out of date index may be included in your document. 


When you create an index using the /INDEX qualifier, whatever parameters 
and other qualifiers you specify affect the processing of both the index file and 
your SDML file. For example, if you specify LNO3_LASER_PRINTER as a 
destination and also use the /PRINT qualifier, both files will be printed on the 
LNO3 laser printer (input-filename.LNO3 and input-filename_INDEX.LNO3). 


The following example shows how an index may be created and printed 
using the /INDEX and /PRINT qualifiers. Both the SDML file (MYREPORT) 
and the index file created from that SDML file (MYREPORT_INDEX) are 
formatted for the LNO3 laser printer and printed on it as specified on the 
command line. VAX DOCUMENT concatenates the printing of the two files 
into a single print job so VMS issues only one print message. 
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$ DOCUMENT myreport.sdml REPORT LNO3 /INDEX /PRINT=(NOTIFY) 
%DOC-I-IDENT, VAX DOCUMENT T1.0-008 
[Tag Translation]... 
4%TAG-I-TAG_IDENT, V1.0 
“%TAG-I-DEFSLOADD, End of Loading of Tag Definitions 
“%TAG-I-ENDPASS_1, End of first pass over the input 
“%TAG-I-FILEWRTOK, File MYREPORT.TEX written 
[Text Formatting]... 
%TEX-I-IDENT, V1.0 
%TEX~I-PAGESOUT, 17 pages written. ; 
-TEX-I-OUTFILENAME, ’DUA1: [DOCFILES]MYREPORT.DVI_LNO3’ 
[Index Generation]... 
%INX-I-IDENT, V1.0 
%INX-I-ENDPASS_1, End of first pass over the input. 
%INX-I-ENDPASS_2, End of second pass over the input. 
%INX-I-CREATED, ’DUA1: [DOCFILES]MYREPORT_INDEX.TEX;1’ created 
[Text Formatting Index]... 
%4TEX-I-IDENT, V1.0 
“4TEX-I-PAGESOUT, 1 page written. 
-TEX-I-OQUTFILENAME, *DUA1: [DOCFILES]MYREPORT_INDEX .DVI_LNO3’ 
[Device Conversion]... 
%DVC-I-IDENT, DVC$LNO3 V1.0 
%DVC-I-PAGESOUT, 18 pages written to file: 

DUA1: [DOCFILES] MYREPORT .LNO3 
[Index Device Conversion]... 
%DVC-I-IDENT, DVC$LNO3 V1.0 
%DVC-I-PAGESOUT, 1 page written to file: 

DUA1: [DOCFILES] MYREPORT_INDEX .LNO3 
ie che cee Uae na ee ga a tee Oe; Oe 
PP orate a tee? Tarde teas 


Job MYREPORT (queue SYS$LNO3, entry 835) started on SYS$LNO3 


$ 





7.2.5 Using Indexing Options 


The following subsections describe the optional indexing keywords that can 
be used with the /INDEX qualifier. These keywords allow you to control 
whether guide headings are used, how master index entries should be 
processed, and how index entries should be sorted. 


These keywords are specified to the /INDEX qualifier as follows: 
/\NDEX[=(index-keyword Piadex-keyword. Wi 

The indexing option keywords are as follows: 

¢ [NO]GUIDE_HEADINGS 

e [NOJOVERRIDE_MASTER 

e SORT 


These keywords are described alphabetically in the following subsections. 
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7.2.5.7 


7.2.5.8 


7.2.5.9 


Using the GUIDE_HEADINGS and NOGUIDE_HEADINGS Keywords 
Use the GUIDE_HEADINGS and NOGUIDE—_HEADINGS keywords to 
specify whether alphabetic headings are inserted into the index whenever an 
entry beginning with a new letter occurs. The GUIDE_HEADINGS keyword 
is the default. 


For example, when the first index entry beginning with the letter “B” is 
encountered, the guide heading “-B-” is placed before it. 


NOGUIDE_HEADINGS suppresses guide headings in the index output file. 


Using the OVERRIDE_MASTER and NOOVERRIDE_MASTER 
Keywords 

The OVERRIDE_MASTER and NOOVERRIDE_MASTER keywords specify 
whether index entries with the MASTER attribute are included in a single- 
document (non-master) index. NOOVERRIDE_MASTER is the default 
keyword, and specifies that index entries marked with the MASTER attribute 
appear only in the master index. 


When the OVERRIDE_MASTER keyword is specified during the creation of 
a single-document index, all index entries created with the MASTER Rey Hore 
attribute are included as entries in the local index. 


When the OVERRIDE_MASTER keyword is specified during the creation of a 
master index, all index entries are included in the master index, not just those 
created with the MASTER keyword attribute. 


Using the SORT Keyword 
Use the SORT keyword to specify the sorting algorithm used to order entries 
in an index. The SORT keyword has the following syntax: 


SORT[=sort-keyword[,sort-keyword[=value]]] 
The following are valid sort-keywords: 


e¢ SORT=LETTER sorts the entries letter-by-letter and ignores spaces and 
hyphens. SORT=LETTER is the default. 


For example the entry “A directory” would be sorted after the entry 
“Add,” because the space is ignored in the sorting and so “A di” is placed 
after “Add” by the sort. 


e SORT=WORD sorts the entries letter-by-letter and treats spaces and 
hyphens as significant. 


For example the entry “A directory” would be sorted with other entries 
that began with “A d” rather than with the entry “Add” because the 
space is treated as a significant part of the entry during the sorting; this 
results in “A d” being placed before “Add” by the sort (since by default 
nonalphabetic characters are sorted before alphabetic characters). 


¢ SORT=NONALPHA positions entries with initial nonalphanumeric 
characters in the index based on the following keyword, supplied with 
the NONALPHA keyword: 


— The AFTER keyword causes entries with initial nonalphanumeric 
characters to be placed at the end of the index. 


— The BEFORE keyword causes entries with initial nonalphanumeric 
characters to be placed at the beginning of the index. 
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— The IGNORE keyword causes entries with initial nonalphanumeric 
characters to be sorted by the first alphanumeric characters in the 
entry. The default is NONALPHA=IGNORE. 





7.3 Creating a Master Index 


VAX DOCUMENT lets you combine the indexes from several documents to 
create a master index for a documentation set. This master index has the 
same format as that of a single-document index, with the following additions: 


¢ Master index entries are cited by both the title of the document from 
which they originated, and by page number. Document titles are 
italicized in these index entries. 


e Index entries that were specified using the MASTER keyword attribute in 
individual documents are automatically entered into the master index. 


You create a master index by performing the following steps: 


1 Create individual intermediate index (INX) files using the /INDEX and 
/KEEP=(INX) qualifiers to the DOCUMENT command. 


2 Create a master index data file, which lists each of the intermediate 
index files with the title of the book from which the index file was 
generated. This file should be named differently than any of your existing 
VAX DOCUMENT files and should have a file type of INX_—LIST. 


3 Run VAX DOCUMENT using the /MASTER_INDEX qualifier and 
specifying the master data file as the input-file-spec parameter. This 
produces a text formatter input file named input-fillename.TEX 


4 Run VAX DOCUMENT (omitting tag translation) using the file you 
produced in the previous step as the input file (input-filename.TEX). 


7.3.1 Creating Intermediate Index Files 


You create intermediate index files whenever you use the /INDEX qualifier to 
create an index. However, VAX DOCUMENT deletes these files unless you 
also specify the /KEEP specifier with the INX keyword argument. You can 
specify these qualifiers, as in the following example: 


$ DOCUMENT mychapter.sdml REPORT LNO3 /INDEX /KEEP=(INX) 


7.3.2 Creating the Master Index Data File 


You create the master index data file just as you would create any ASCII 
file (by using an editor, using the VMS CREATE command, and so on). The 
master index data file lists all the index files that are to be collated into the 
master index. It has a default file type of INX—LIST. 


Each master index entry is associated with the book that it came from. 

You can use the /BOOK_IDENTIFIER qualifier inside of the data file to 
specify the title of that book. If you do not specify the /BOOK_IDENTIFIER 
qualifier, the title of the book will be the file name of the INX file. 
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The /BOOK_IDENTIFIER qualifier has the following syntax: . 
/BOOK_IDENTIFIER="book-title” 


If you specify the /BOOK_IDENTIFIER without the book-title value, 

VAX DOCUMENT issues an error message. If you want to generate a master 
index without book titles, you can specify null strings to the /BOOK_— 
IDENTIFIER qualifier for all your intermediate index files as follows: 


2041. INX/BOOK_IDENTIFIER="_" 
2323. INX/BOOK_IDENTIFIER=" " 


Use the following rules in entering intermediate index file specifications 
(filename.INX files) into the master index data file: 


e Each index file specification must be entered on a single line in the data 
file with no other characters preceding it. 


e Each index file specification must be an intermediate indexing file 
(filename.INX) and must be specified completely including the INX 
file type. You can also use a process logical name for the intermediate 
indexing file. 


¢ Comments can be made in the data file using the exclamation point (!) 
character. This character excludes from processing only those characters 
that follow it on the same line. 


The following is a sample of a master index data file. The books listed in this 
file all have numeric names and so the /BOOK_IDENTIFIER qualifier was 
used to specify more meaningful book titles. 


!Master index data file 
!Created Dec 1, 1986 
{Updated Jan 4, 1987 

! 


2041. INX/BOOK_IDENTIFIER="System Generation" 
2323. INX/BOOK_IDENTIFIER="Writing I/O Driver" 
2050. INX/BOOK_IDENTIFIER="MCR Operations" 
2053. INX/BOOK_IDENTIFIER="Program Development" 
2054 . INX/BOOK_IDENTIFIER="Executive" 

2055 . INX/BOOK_IDENTIFIER="Task Builder" 

2056. INX/BOOK_IDENTIFIER="System Library" 

2057 . INX/BOOK_IDENTIFIER="Utilities" 

2059. INX/BOOK_IDENTIFIER="I/O Drivers" 

2176. INX/BOOK_IDENTIFIER="Release Notes" 


7.3.3 Creating the Master Index File 


You create the master index file by using the DOCUMENT command twice: 
once to create an input file for the text formatter from the master index date 
file, and once to process the text formatter input file into a printable file. 


You create a text formatter input file from the master index data file by using 
the /MASTER_INDEX qualifier on the DOCUMENT command line and 
specifying the master data file as the input-file-spec parameter. The master 
data file has a default file type of INX_LIST. This produces a text formatter 
input file named input-file. TEX 
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In the following example, the master data file MYMASTER.INX_LIST is 
processed using the /MASTER_INDEX qualifier: 


$ DOCUMENT MYMASTER.INX_LIST REPORT LNO3 /MASTER_INDEX 
%DOC-I-IDENT, VAX DOCUMENT V1.0 

[Master Index Generation]... 
%INX-I-IDENT, V1.0 

4INX-I-ENDPASS_1, End of first pass over the input. 
%INX-I-ENDPASS_2, End of second pass over the input. 
%INX-I-CREATED, *DUA1: [DOCFILES]MYMASTER.TEX;1’ created 
$ 


After you have created the text formatter input file, use that file as the input 
file to VAX DOCUMENT and process it without the tag translator (/ NOTAG_ 
TRANSLATOR). 


In the following example, the text formatter input file MYMASTER.TEX is 
processed using the /NOTAG_TRANSLATOR qualifier to create a printable 
master index file for the LNO3 laser printer named MYMASTERINDEX.LNO3. 


$ DOCUMENT/NOTAG MYMASTER.TEX REPORT LNO3 
[Text Formatting]... 
“%TEX-I-IDENT, V1.0 
“%TEX-I-PAGESOUT, 2 pages written. 
-TEX-I-OUTFILENAME, °’DUA1: [DOCFILES]MYMASTER.DVI_LNO3’ 
[Device Conversion]... 
“#DVC-I-IDENT, DVC$LNO3 V1.0 
Z%DVC-I-PAGESOUT, 18 pages written to file: 
DUA1 : [DOCFILES] MYMASTER . LNO3 
LP int ig Fal edie 


Job MYMASTER (queue SYS$LNO3, entry 835) started on LNO3 


$ 


8 Special Features 


This chapter describes various special features that you can request in the 
formatted output. The features include the following: 


e Providing emphasis, such as bolding or italicizing 
e¢ Using footnotes 

e §=6Using callouts 

e Drawing large braces and brackets 

¢ Controlling case 

¢ Formatting mathematical formulas 

e Providing quotation marks 

e Placing parentheses around a single character 


e Drawing horizontal and vertical ellipses 





8.1 Providing Emphasis 


There are numerous methods available to lend emphasis to words or phrases 
in your printed output. In most methods, you pass the text to be emphasized 
as an argument to a special tag. 


This section discusses the tags as global tags, because they are always 
available for use. The formatted effect of each tag is also described here, — 
but you should be aware that the effect can differ depending on the doctype. 


The <EMPHASIS> tag provides italic or bolding emphasis. At first glance, 
those capabilities would seem to be adequate for most purposes, but in fact 
there are many additional tags that provide emphasis. The variety of tags 
relates to the numerous possible reasons for emphasis. 


The reasons vary: the word might be the name of something, it might be 

a reserved word in a programming language, or it might be being used for 
the first time in your book. In a generic markup language, you should be © 
tagging the word according to the reason for its emphasis, not according to 
the desired effect in the formatted output. In other words, you should be 
thinking, “This is the first use of this phrase,” and not thinking, “This phrase 
needs to be italicized.” 


Accordingly, the tags for emphasis attempt to name the reason for the 
emphasis rather than to name the formatting effect. If you use the tags 
properly in your SDML files, the book designer is free to change the effect 
for a single tag. Thus, the tag that lends emphasis to a first-time use, 
<NEWTERM> , might be changed from simple italic to an italic font that is 
larger or bolder. However, another tag that also gives an italic effect might be 
left unchanged. If you fail to distinguish these two uses when you code the 
SDML file (by coding both with the <EMPHASIS> tag), you will not be able 
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to make a selective change in the type of emphasis for the <NEWTERM> tag 
without affecting your output. 


A description of each of the emphasis tags follows: 
e <GREF> and <NEWTERM> 


These two tags are similar, in that they are used to refer to a word or 
phrase in a special first-time use, where the word is about to be defined. 
Use the <GREF> tag if the word is also in the glossary. 


bd <KEYWORD> 


Use this tag in a discussion of a word or phrase from a computer program 
or a programming language (sometimes called a “reserved word”). 


° <VARIABLE> 


When you write about the effect of executing some computer program 
command or programming language statement, you may want to refer to 
a variable by name and then refer to its value. Tagging the variable name 
with this tag ensures that it has the proper emphasis in the output. 


° <EMPHASIS> and <UNDERLINE> 


These tags are appropriate for situations where the other emphasis tags 
are unsuitable. Because they specify the formatting effect in the output 
rather than the reason for the effect, use them sparingly. 


e  <NOTE> 


This tag has a pronounced. formatting effect, because it not only bolds 
the text, but it breaks the text out of its surrounding text and supplies an 
attention-getting heading. An example of an appropriate use follows: 


. .. the unary minus in this expression. 
<NOTE>Observe how the precedence of the unary minus operator 
requires the use of parentheses in this expression. 
<ENDNOTE> 
This example might produce the following: 


... the unary minus in this expression. 


Note: Observe how the precedence of the unary minus operator requires the 
use of parentheses in this expression. 


Table 8-1 shows each of the tags (except <NOTE> ) used in text. Your output 
might differ, according to the design chosen for your system. 
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Table 8—1 Examples of Emphasis Tags 





Coding Output" 

The <GREF> (abc def) letters The abc def letters 
The <NEWTERM> (abc def) letters The abc def letters 
The <KEYWORD> (abc def) letters The abc def letters 
The <VARIABLE> (abc def) letters The abc def letters 
The <EMPHASIS> (abc def) letters The abc def letters 
The <EMPHASIS> (abc def\BOLD) letters The abc def letters 
The <EMPHASIS> (abc def\SMALLCAPS) letters The ABC DEF letters 
The <EMPHASIS> (abc def\SMALL_BOLDCAPS) The asc ber letters 
letters 

The <UNDERLINE> (abc def) letters The abc def letters 


'The output of the samples included in this table is dependent on the doctype 
and printing device used. 


As you read about each tag, remember that the punctuation that follows a 
bolded or italic font should be printed in the same font. This means that you 
should always include the punctuation as part of the argument. 





8.2 Using Footnotes 


Three tags are available for creating a footnote, the <FOOTNOTE> tag, the 
<FOOTNOTE_TEXT> tag, and the <FOOTREF> tag. Their syntax is as follows: 


<FOOTNOTE> (char\footnote-text) 
<FOOTNOTE. TEXT> (char\text) 
<FOOTREF>(char-1[\char-2...\char-9]) 


A footnote consists of two parts, the character that appears as a small 
superscript in the text, and the correspondingly noted sentence or paragraph 
at the foot of the same page. The <FOOTNOTE> tag provides both the 
superscript and the actual text. 


You supply the superscript character as the first argument of the 
<FOOTNOTE> tag and the footnote text as its second argument. Place 

the <FOOTNOTE> tag precisely where you want the number to appear. This 
is generally at the end of a phrase or sentence and usually after the closing 
punctuation. Do not leave space between the punctuation and the opening 
angle bracket of the <FOOTNOTE> tag. 


VAX DOCUMENT places the character as a small superscript in the text, and 
floats the text to the foot of the page. 


You can use the <FOOTREF> tag to place the same number at another place 
in the text, although this practice is discouraged. 


Use the <FOOTNOTE> and <FOOTREF> tags to create footnotes in tables. 
Table footnotes appear at the foot of the table, rather than at the foot of the 
page. When you need a footnote in a table, place the <FOOTNOTE> tag at 
the beginning of the table immediately after the <TABLE_SETUP> tag. Then, 
at the desired points within the table, supply the <FOOTREF> tag. With this 
method, you can place the same superscript at more than one point in the 
table. 
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Using Callouts 
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For multipage tables, the footnote text repeats on each page that carries a 
reference to that note, provided that you call the footnotes out in the table 
heading. If the reference is in the heading, the footnotes and references 
appear on all pages of the table. 


The output device must have a character font that displays these superscript 
characters. 


The <FOOTNOTE_TEXT> tag is necessary when a footnote must be provided 
on a title or copyright page or in the context of header-level text. 





Three tags are available for annotating examples by what is termed a callout. 
The callout is a number that draws special attention, possibly by being 
printed as a white digit on a black background, for example @, or through 
some other graphic display. Writers frequently display numbers this way to 
mark points in an example that are then explained by entries in a numbered 
list that follows the example. The numbers of the list entries are displayed in 
the same format (white digit on a black background). 


Callouts are used within a restricted area of the SDML file that you indicate 
by <CALLOUTS> and <ENDCALLOUTS> tags. Within the example or text that 
is to be annotated, you locate the desired numbers by using the <CO> tag 
with the correct number as its argument. Following the area of the callouts, 
you supply the list of explanations or notes by introducing the list with the 
<LIST> (CALLOUT) tag. The list entries are introduced by the <LE> tag 
and the list is ended with the <ENDLIST> tag. However, when the list is 
formatted, the number of each entry in a noted-list is displayed as a white 
number on a black background. 


When you begin an example that will include callouts, you can specify 
\PREFIX as an argument of the <CALLOUTS> tag. This causes the example 
to be indented, leaving a gutter on the left. Then, if you specify the <co> 
tag at the left end of an example line, the callout number will be placed in 
the left gutter. In this way, VAX DOCUMENT does not disturb the normal 
indentation that might be important in your example. Here are two identical 
example lines, coded as follows: 


<CO>(2)PROGRAM Calculator (INPUT, OUTPUT); 
TYPE 
Yes_No = (Yes, No); 


Without the \PREFIX argument, the output format is as follows: 


@PROGRAM Calculator (INPUT, OUTPUT); 
TYPE 
Yes_No = (Yes, No); 


With the \PREFIX argument, the output format is as follows: 


@ PROGRAM Calculator (INPUT, OUTPUT); 
TYPE 
Yes_No = (Yes, No); 


Callouts are not limited to use within monospaced examples. For example, 
if you want to number certain paragraphs of text, or if you want to place 
callouts into a template to distinguish one group of entries from another, 
you can surround the area with the <CALLOUTS> ... <ENDCALLOUTS> 
tags and then place the <CO> tags wherever numbers are desired. For text 
paragraphs, you must be sure to place the <CO> tag after the <P> tag 
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that starts a paragraph, and in other cases you may have to place the <CcO> 
tag within an argument list so that the callout number is associated with the 
proper text elements. If you use the \PREFIX argument on the <CALLOUTS> 
tag when you put callouts on paragraphs, the paragraphs are not indented, 
but the callout number is pushed to the left of the normal text margin, as 
follows: 


@ This is a paragraph with a callout. The \PREFIX argument was used on the 
<CALLOUTS> tag. 


If you need to refer to a noted-list entry, you should use the <CALLOUT_ 
REF> (callout-number) tag. This tag need not occur within the 
<CALLOUTS> ... <ENDCALLOUTS> tags. The word “callout” is editorial 
jargon and is probably not in your reader’s vocabulary, so do not write “see 
callout ©.” Instead, refer to the numbered item as a note. For example, “see 
note ©.” 


Each device treats callouts in a distinct way typographically. This might vary 
from device to device according to the available fonts. 


8.4 Drawing Large Braces and Brackets 


When you are documenting the syntax of a programming language, you often 
use the convention that shows choices (or options) as items that are vertically 
stacked inside large brackets or braces. You tell the reader that the brackets 
mean an optional choice and the braces mean a required choice. 





These brackets or braces are produced in the output by using the 

<LIST> (STACKED) tag. The <LIST> (STACKED) tag works like other list 
tags in that the list begins with the <LIST> tag, each element is introduced 
by the <LE> tag, and the list is ended by the <ENDLIST> tag. The size of 
the bracket or brace is adjusted automatically to enclose the list elements and 
the enclosed list is aligned with other elements on the same line. Here is an 
SDML file excerpt: 


<P> 

SET 

<LIST> (STACKED\BRACES) 
<LE>LOZENGE 
<LE>UNDERSCORE 
<LE>GRAPHIC 

<ENDLIST> 

CURSOR 

<LIST> (STACKED\BRACKETS) 
<LE>ON 

<LE>OFF 

<ENDLIST> 

(Default is ON) 


The result is as follows: 


LOZENGE an 
SET 4 UNDERSCORE } CURSOR (Default is ON) 


GRAPHIC at 
The output device must have a character font that displays these braces and 
brackets. 
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Controlling Case 


Usually, you control the case of the letters in the output by the case of the 
letters in the SDML file. If you put a lowercase letter in the SDML file, it 
remains lowercase in the output. In rare cases, an argument to a tag is forced 
into upper- or lowercase by the action of the tag. If you want to avoid this 
case conversion, you can force letters into the output (in the stated case) by 
using either the <UPPERCASE> or <LOWERCASE> tags. 





Providing Quotation Marks 


Many keyboards provide a key for a quotation mark, sometimes called 
a double-quote, that produces an effect such as shown in the following 
example: 


"Hello, sailor!" 


The quotation marks used by typesetters, on the other hand, produce an 
effect such as the following: 


“Hello, sailor!” 


In software documentation, you might want the programmer’s double-quote 
character ("). Occasionally, you will also want to surround something with 
the typesetter’s quotation marks (“ ”). 


When you want the typesetter’s quotation marks around a string, pass the 
quoted string as an argument to the <QUOTE> tag. For example, to obtain 
“Hello, sailor!” you must specify the following: 


<QUOTE>(Hello, sailor!) 


Include ending punctuation as part of the argument to the <QUOTE> tag if 
you want it to appear inside the quotation marks. 


VAX DOCUMENT outputs one of the typesetter’s quotation marks (the ”) 
when it finds the ASCII double-quote character (") in a proportionally spaced 
part of your SDML file. However, in an example, where monospaced text is 
the default, the ASCII double-quote character is output as ("). 


If you need to show the ASCII double-quote character in text as it normally 
appears in a listing or on the screen (as "), code it with the <DOUBLE_ 
QUOTE> tag. Suppose you want to show the following: 


.. in the expression NAME := 
"Smith", 


You must code this text as follows: 
in the expression NAME := <DOUBLE_QUOTE>Smith<DOUBLE_QUOTE>, 


Similarly, the text output for a single-quote character (ASCII 39) is the 
apostrophe (’), so if you need to show the ASCII single-quote character in 
text as it normally appears in a listing or on the screen (as '), code it with the 
<SINGLE_QUOTE> tag. Suppose you want to show the following: 


. . in the expression NAME := 
*Smith’, 


You must code this text as follows: 


in the expression NAME := <SINGLE_QUOTE>Smith<SINGLE_QUOTE>, 
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This might appear complicated, but you often achieve what you want with 
minimum effort. The rules are as follows: 


1 In examples, where you are illustrating what appears on the screen, use 
single- or double-quote characters. Just press the keyboard’s single- or 
double- “quote key. Because it is within an example, the key results in 
the screen’s single- or double-quote character (‘ or ") rather than the 
apostrophe or the typesetter’s quotation mark. 


2 In text, when you want the apostrophe, press the keyboard’s single-quote 
key. Because it is within text, it prints as an apostrophe. 


3 In text, when you need to cite text from another source or cite an excerpt 
of a speech, use the <QUOTE> tag, to obtain the typesetter’s quotation 
marks. 


4 You will rarely want to show the screen or listing version of the single- 
quote key (') or the double-quote key (“) in text. However, when 
necessary, use the <SINGLE_QUOTE> and <DOUBLE_QUOTE> tags. 


The output device must have a character font that displays these typesetter’s 
characters. 





8.7 Placing Parentheses Around a Single Character 


When you enclose something in parentheses in your text, the opening and 
closing parentheses snug up against the enclosed text. However, if you are 
enclosing a single character, especially a punctuation character, the close 
placement of the parentheses overwhelms the character, for example (,). If 
you anticipate this possible problem and place a space on either side of the 
character, (, ), you run the risk that a line break will occur at one of the 
spaces, leaving some of the parenthesized character at the end of one line and 
the rest at the start of the next line. 


Instead, you can pass the character as an argument to the <PARENDCHAR> 
tag, which will supply the parentheses and some extra space around the 
character, for example, (,). The argument to <PARENDCHAR> need not be 
limited to one character, but if the characters being parenthesized are letters 
or digits the <PARENDCHAR> tag may be unnecessary. 


The output device must have a character font that displays these 
proportionally spaced characters. 





8.8. Drawing Horizontal and Vertical Ellipses 


Writers sometimes use ellipses to emphasize the omission of text. It is not 
possible to achieve proper spacing of the ellipses by simply supplying three 
periods, because periods snug up against the preceding character. If you 
insert space characters between them, you run the risk that a line break will 
occur between them. Accordingly, use the <HELLIPSIS> tag to supply a 
horizontal ellipsis ( ... ). 


To create a vertical ellipsis, use the <ELLIPSIS> tag. 
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Special Features 





8.9 Showing Special Characters 


VAX DOCUMENT provides facilities for including special characters in the 
text. Among the special characters supported are the following: 


¢ Mathematical special symbols, such as operators and the uppercase Greek 
letters 


¢ Multinational Character Set (MCS), which includes such symbols as the 
British pound, the Japanese yen, umlauts, and so forth 


¢ Opening double brackets and closing double brackets 


The <MATH_CHAR> tag allows you to specify a wide range of mathematical 
symbols. The <McS> tag offers the full range of symbols in the DIGITAL 
Multinational Character Set. The <SPECIAL_CHAR> tag supports a series of 
keywords that identifies such special symbols as the trademark symbol, the 
dagger, and the opening double bracket and closing double bracket. 





8.10 Using Formatting Tags 


The following tags provide special formatting: 


bd <PAGE> 
° <LINE> 
7 <KEEP> 


° <FINAL CLEANUP > 


Be aware when using these tags that your output can vary between devices. 
If you were to use these tags in a file processed for an LNO1 printer, your 
output could look much different than you planned if you were to reprocess 
your file for a PostScript device. Adding or deleting text can also affect the 
output when these tags are used. 


8.10.1 Specifying Page Breaks 


Use the <PAGE> tag whenever you need to force the text to begin on a 
new page of output. You can optionally direct whether the text continuation 
should begin on the next even- or odd-numbered page. 


8.10.2 Specifying Line Breaks 


Use the <LINE> tag whenever you must force text to begin on a new line 
of output. It is possible to include arguments that determine the amount of 
space before the next line or whether the text should be indented. 


In addition, the <CENTER_LINE> tag identifies a line of text that is to be 
centered within the current text margins. Its arguments also permit you to 
specify the amount of space introduced prior to outputting the line. ~ 


The <RIGHT_LINE> tag right-adjusts a line of text within the current text 
margins. Optionally, you can specify that a large or small amount of space is 
desired. 


Special Features 


8.10.3 Keeping Text on a Single Line 


The <KEEP> tag allows you to specify text that must be forced to occur on 
a particular line of output and, therefore, must not be either hyphenated 
or broken at an existing hyphen. For example, this is important whenever 
it is undesirable to break a hyphenated word, such as a product name 

like PDP-11 or when a widow or orphan might be created by automatic 
hyphenation. 


Note that when you use the <KEEP> tag in combination with the 
<HYPHENATE> tag, the hyphenation does not occur; that is, the <KEEP> 
tag overrides the normal effects of the <HYPHENATE> . 


8.10.4 Controlling Page and Line Breaks for Final Production 


The <FINAL_CLEANUP> tag is useful for performing specialized adjustments 
of line or page breaks during final production, when the use of a particular 
output device or some other consideration indicates that the normal page or 
line break should be overridden. 
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Doctype-Independent Tag Descriptions 


This chapter includes descriptions of all doctype-independent (globally used) 
tags. The tags are listed alphabetically. 


<ABSTRACT> 


<ABSTRACT> 





Begins a summary description of a document on the title page or part page 
of a document. 





FORMAT <ABSTRACT> [(title)] 





ARGUMENTS title 


Specifies a title for the abstract. 





related tags ¢ = <FRONT_MATTER> 
e  <TITLE_PAGE> 


. <PART_PAGE> 








restrictions Can be used only in the context of a <TITLE_PAGE> or <PART_PAGE> tag. 
required <ENDABSTRACT> 
terminator 





DESCRIPTION The <ABSTRACT> tag begins a summary description of a document on the 
title page or part page of a document. 





EXAMPLES See the examples in the discussion of the <PART_PAGE> tag. 


i 
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<ACCENT> 


<ACCENT> 


Supplies a freestanding accent mark. 





FORMAT <ACCENT> (accent-mark) 





ARGUMENTS _accent-mark 


Specifies one of the following keywords to indicate the accent mark: | 











* UMLAUT 

e ACUTE 

°¢ GRAVE 
related tags e  <Mcs> 
restrictions Invalid in math. 
required None. 


terminator 





DESCRIPTION The <AccENT> tag supplies a freestanding accent mark in the printed 
out 





put. 
<P>Accents used in the DEC Multinational Character Set include the 
following: . 
<LIST> (UNNUMBERED) 


<LE>Grave accents <PARENDCHAR>(<ACCENT> (GRAVE) ) 
<LE>Acute accents <PARENDCHAR>(<ACCENT> (ACUTE) ) 
<LE>Umlauts <PARENDCHAR>(<ACCENT>(UMLAUT) ) 
<ELS> 


This example may produce the following output: 

Accents used in the DEC Multinational Character Set include the following: 
°e Grave accents (*) 

e Acute accents () 


e Umlauts (”) 


i 
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<ALIGN_AFTER> 


<ALIGN_AFTER> 


Allows you to position formatted text in a list. 





FORMAT 


<ALIGN_AFTER> (text) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


text 


Specifies the string under which you want to align a stack of text. 





¢ = <LINE> [(INDENT)] 
e = =<LIST> (STACKED) 


° <ALIGN_NUMBER> 





Invalid in math. 





None. 





DESCRIPTION The <ALIGN_AFTER> tag enables you to position text in a list after the text 


specified in the argument. 





EXAMPLE 


<LIST> (STACKED\BRACES) 


<LE><ALIGN_AFTER> (UN) NUMBERED 


<LE>UNNUMBERED 
<ELS> 


This example shows how to create a stacked list where the text is aligned 
after the the string “UN”. This example may produce the following output: 
{ NUMBERED \ 

UNNUMBERED 


<ALIGN_CHAR> 


<ALIGN_CHAR> 


Identifies a nonprinting character to be used to align numeric information 
within a column of a list or table. 





FORMAT 


<ALIGN_CHAR> (character [ \ DELTA)]) 





ARGUMENTS 


related tags 


character 
Specifies the character to be used for alignment. 


The character must be one of the following special characters: 


a a sa 
% * ~ @ 
bo Se 


DELTA 


Specifies the character indicated for alignment is replaced on output with a 
delta character to indicate spacing. 





bd <ALIGN—AFTER> 
° <TABLE_ROW> 


® <ALIGN_NUMBER> 











restrictions Invalid in math. 
Invalid in monospaced examples. Aligned characters might be referenced in 
an example, but the <ALIGN_CHAR> and <ENDALIGN—CHAR> tags must 
occur outside the example. 

requ i red <ENDALIGN—CHAR> 

terminator 

DESCRIPTION The <ALIGN_CHAR> tag identifies the character that is to be used to signify 


a space in a table row. The tag translator replaces each occurrence of the 
character with a space. The space is the same width as the numeric characters 
in the font that is active. (All numeric characters of a font have a uniform 
width.) 


Items in a column are aligned on the left by default. You may want to display 
a column of numbers aligned on the right. You can use the <ALIGN_CHAR> 
tag to define “#,” for example, as the alignment character. You make all 

the numeric entries of equal length by prefixing the shorter entries with the 
alignment character. Because the numeric characters are of uniform width, 
they will then align on the right. You can also use the alignment character to 
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<ALIGN_CHAR> 


add space within the number. For example, you could separate the digits of a 
number at the thousands position. 





EXAMPLES 
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<ALIGN_CHAR> (#) 

<TABLE> 

<TABLE_SETUP> (2\16) 

<TABLE_ROW> (0#123#456#781\01234567 . 89) 
<TABLE_ROW> (#######35#279 \ HHHHHHHE . O) 
<TABLE_ROW> (#4444434 1 \####1429 . 857) 
<ENDTABLE> 

<ENDALIGN_CHAR> 


This example defines the number sign as the alignment character. The 
number sign is then used to align the columns in a two-column list. This 
example may produce the following output: 


O 123 456 789 01234567.89 
35 279 6.0 
4 361 1429.857 


<TABLE> 

<TABLE_SETUP> (2\16) 

<TABLE_ROW> (0123456789\01234567 . 89) 
<TABLE_ROW>(35279\6.0) 

<TABLE_ROW> (4361\1429. 857) 
<ENDTABLE> 


This example shows the two-column list used in the previous example 
without the use of an alignment character. This example may produce the 
following output: 


0123456789 01234567.89 
35279 6.0 
4361 1429.857 


<P>The sum may be padded on the left with blanks, resulting in 
<ALIGN_CHAR> (#) 

<KEEP> (’ ###7 56’) 

<ENDALIGN_CHAR> 


This example shows how blank output characters can be represented using 
the <ALIGN_CHAR> tag. This example may produce the output: 


The sum may be padded on the left with blanks, resulting in ' 7.56’ 


<P>The sum may be padded on the left with blanks, resulting in 
<ALIGN_CHAR> (#\DELTA) 

<KEEP> (’ ###7 .56’) 

<ENDALIGN_CHAR> 


This example shows how delta output characters can be represented using the 
<ALIGN_CHAR> tag. This example may produce the output: 


The sum may be padded on the left with delta characters, resulting in 
‘AAA7.56' 


<ALIGN_NUMBER> 


<ALIGN_NUMBER> 


Specifies a numeric value with alignment characters. 





FORMAT 


<ALIGN—NUMBER> (number) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


number 

Specifies a number, which can include commas and decimal points, that is to 
be aligned with other numbers in the same column. Fields in the number that 
are to be left blank may contain pound sign (#) characters representing blank 
numbers or semi-colon (;) characters representing commas or decimal points. 





* <ALIGN_AFTER> 
* <ALIGN_CHAR> 


© <TABLE_ROW > 





Invalid in math. 





None. 





DESCRIPTION 


The <ALIGN_NUMBER> tag lets you align columns of numbers in a table, 
when the numbers you need to enter have suppressed leading or trailing 
fields. You enter the number using the pound-sign and semi-colon characters 
to represent fields in the number that are to be blank on output. 


Items in a column are aligned on the left by default. You may want to 
display a column of numbers aligned on the right, or aligned around the 
decimal point. To do this, you use the <ALIGN_NUMBER> tag to tag each 
number. 





EXAMPLES 


' <table> 
<table_setup>(2\8) 


<table_row>(one\<align_number> (100,000,000. ##) ) 
<table_row>(one\<align_number> (###; ###; 240.40) ) 
<table_row>(one\<align_number> (###; ###H# ; #i## .60) ) 
<table_row>(one\<align_number> (###; 230,425) ) 


<endtable> 


is 
~l 


<ALIGN—_NUMBER> 


This example shows a series of numbers aligned at the decimal point. This 


example may produce the output: 


one 100,000,000. 
one 240.40 
one .60 
one 230,425 


8 <table> 
<table_setup>(3\15\10) 


<table_heads>(Item\Net Revenue\Percentage) 


<table_row>(Fish knives\<align_number> (#; #20; 435; ##) \<align_number> (/#10 . 44) ) 
<table_row>(Clam cleaners\<align_number>(1,432,064.23)\<align_number>(%#45 . O#) ) 
<table_row>(Shrimp peelers\<align_number> (#; ###; 245; ##) \<align_number> (A### .86) ) 


<endtable> 


This table may produce the output: 


Item 
Fish knives 


Clam cleaners 


Shrimp peelers 


Net Revenue 


1,432,064.23 


Percentage 
% 10.44 

% 45.0 

% .86 


<AMPERSAND> 


<AMPERSAND> 


Supplies an ampersand within an argument to a tag or in math. 





FORMAT <AMPERSAND> 





ARGUMENTS None. 











related tags ¢ The following tags label other characters that must be tagged when they 
occur in an argument to a global tag: 
<BACKSLASH> 
<CPAREN> 
<OPAREN> 
<VBAR> 
restrictions Can only be used within an argument to a tag. 
required None. 
terminator 





DESCRIPTION Use the <AMPERSAND> tag to output an ampersand within an argument to 
; a tag. Outside of an argument to an SDML tag, use the regular ampersand 
character rather than the tag. 


The ampersand has a special meaning to the tag translator when it occurs 
within an argument to a tag. If you use a literal ampersand within an 
argument, it may be misinterpreted, and may cause an error in your output. 
Use the <AMPERSAND> tag to avoid any misinterpretation. 





EXAMPLE 


<SUBHEAD1>(Continuing the Line with <AMPERSAND> ) 
<P>Your BASIC statement may be formatted over two or more lines 
by terminating all lines but the last with an ampersand (&). 


This example can produce the following output. 


Continuing the Line with & 


Your BASIC statement may be formatted over two or more lines by 
terminating all lines but the last with an ampersand (&). 


r 
© 


<APPENDIX> 


<APPENDIX> 


Begins an appendix. 





FORMAT 


<APPENDIX> (appendix-title[ \ symbol-name]) 





ARGUMENTS 


related tags 


appendix-title 
Specifies the title for the appendix. 


symbol-name 


Specifies the symbol-name to be used in all cross-references to this appendix. 


The value of the symbol in the cross-reference file is the number assigned to 
the appendix. If the appendix is an element in a book, the appendix number 
is determined based on the position of the appendix with respect to other 
appendixes in the book. 


If the file being processed is not currently part of a book, the first appendix 
in the source file will be lettered A, and additional appendixes will be 
sequentially lettered thereafter. 


If the file containing this tag is to be included in a bookbuild, the symbol- 
name is required. 





bg <SET_APPENDIX_LETTER> 











restrictions None. 

required <ENDAPPENDIX> 

terminator 

DESCRIPTION The <APPENDIX> tag starts the appendix section of a book and can contain 
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any number of other tags. Appendixes contain supplementary material at the 
end of a book. 


~ 


<BACKSLASH> 


<BACKSLASH > 


Supplies a backslash within an argument to a tag. 





FORMAT <BACKSLASH> 





ARGUMENTS = None. 











related tags _. e The following tags label other characters that must be tagged when they 
. eee occur in an argument to a global tag: 
se <AMPERSAND> 
<CPAREN> 
* <CPAREN> 

<VBAR> 

restrictions Can be used only within an argument to a tag. 

required None. 

terminator 


DESCRIPTION Use the <BACKSLASH> tag to output a backslash within an argument to a tag. 
Outside of an argument to an SDML tag use the regular backslash character 
rather than the tag. 


Because the literal backslash character is used to separate the arguments in 
the argument list, you must use the <BACKSLASH> tag to include a backslash 
as part of your argument. 


EXAMPLE 


<SUBHEAD1>(Using the Backslash (<BACKSLASH>) ) 
<P>Use the backslash character (\) to separate BASIC statements 
on the same line. 


This example may produce the following output: 


Using the Backslash (\) 


Use the backslash character (\\) to separate BASIC statements on the same 
line. 


As shown in this example, a simple backslash character is used in ordinary 
text. When a literal backslash is used in the argument to the <SUBHEAD1> 
tag, the text following the backslash is not output. 
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<BOX> 


<BOX> 


Produces a box that surrounds a user-specified character string. 





FORMAT <BOX> (label) 





ARGUMENTS _label 


Specifies the character string to be surrounded by the box. 





related tags None. 





restrictions Valid in any context except math. 


The character string must be 15 characters or fewer. The box format might 
not be available for all output devices. 





required None. 
terminator 





DESCRIPTION The <Box> tag produces a box that surrounds a user-specified character 
string in the printed output. By using the keyword TEXT, the character string 
will be surrounded by angle brackets rather than a box. 





EXAMPLE 


<P>In EDT, the <BOX>(GOLD) key 
changes the function of the other keys on the keypad. 


This example produces the following output: 


In EDT, the key changes the function of the other keys on the keypad. 
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<CALLOUT> 


<CALLOUT> 


Labels a callout in an example. The <CALLOUT> tag is identical to the 
<CO> tag. 





FORMAT <CALLOUT> [(number)] 





ARGUMENTS number 


Specifies the number to be used as the callout. If not specified, the next 
number in the callout sequence is output. 





related tags °  <CALLOUTS> 
<CALLOUT_REF> 


<CcO> 
<LIST> (CALLOUT) 








restrictions None. 
required None. 
terminator | 





DESCRIPTION The <cALLoutT> tag identifies a number that will be printed as a white 
letter in a black box in an example. It is used within the <CALLOUTS> and 
<ENDCALLOUTS> tags. 





EXAMPLES See the examples in the discussion of the <CALLOUTS> tag. 


<CALLOUT_REF> 





<CALLOUT_REF> 


Labels a reference to a callout in text. 





FORMAT <CALLOUT_REF> (callout number) 





ARGUMENTS callout number 


Specifies the number to be included in the callout. 





related tags * = <CALLOUTS> 
| ® = <CALLOUT> 


e  <cOo> 
e ©The following tags label other types of ferences: 


<REFERENCE> (symbol) 
<GREF> (reference text) 





restrictions Invalid in the context of math. 


Cannot be used in examples. 





required None. 
terminator 





DESCRIPTION The <cCALLOUT_REF> tag identifies a reference to a number that will be 
printed as a white letter in a black box. It is used in conjuction with the 
<CALLOUT> tag. 7 





EXAMPLE 


<P>In <REFERENCE>(page_transitions_fig) , 

callout <CALLOUT_REF> (1) 

labels the beginning of the process. The initial conditions are the same 
as in the previous figure and the copy-on-reference bit is set. 


This example may produce the following output: 


In Figure 3-3, callout @ labels the beginning of the process. The initial 
conditions are the same as in the previous figure and the copy-on-reference 
bit is set. 
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<CALLOUTS> 


<CALLOUTS> 


Labels the beginning of a series of callouts contained in an example and 
enables the use of the <CALLOUT> and <CO> tags. (<CALLOUT> and 
<CO> are identical in their use.) 





FORMAT <CALLOUTS> /[([callout-number] \ [PREFIX]])] 





ARGUMENTS callout-number 


Sets the number with which to begin numbering the callouts. If no number is 
specified, the numbering begins with one. 


PREFIX 


Determines that the callouts will appear before the line they label, rather than 
at the end of the line. All callouts in any one example must precede the line 
they label or appear inside or at the end of the line they label. Location of 
the callouts cannot be mixed. 





related tags ° — <CALLOUT> 


<CO> 


<CALLOUT_REF> 
<LIST> (CALLOUT) 





restrictions The <CALLOUTS> and <ENDCALLOUTS> tags must surround the examples 


within which the callouts are used. 


The PREFIX argument, if specified, must be the second argument. The first 
argument can be null. For example, <CALLOUTS> (\PREFIX) is valid. 





required <ENDCALLOUTS> 
terminator 





EXAMPLES 


<CALLOUTS> 
<CODE_EXAMPLE> 
DO WHILE (“EOF); <CALLOUT> 

READ FILE(INFILE) INTOCY) ; 
PUT LIST(Y); | <CALLOUT> 
END; 

<ENDCODE_EXAMPLE> 

<ENDCALLOUTS> 

<LIST> (CALLOUT) 

<LE>This is a <KEYWORD>(DO) statement. 

<LE>This <KEYWORD>(PUT) statement outputs the line read. 

<ENDLIST> 


<CALLOUTS> 


This example may produce the following output: 


DO WHILE (“EOF); @ 
READ FILE(INFILE) INTOCY); 
PUT LIST(Y); 
END; 


@ This is a DO statement. 
@® This PUT statement outputs the line read. 


YJ] — <CALLOUTS> (3\PREF IX) 
<CODE_EXAMPLE> 
<CALLOUT> DO WHILE (“EOF) ; 
READ FILE(INFILE) INTO(Y) ; 
<CALLOUT> PUT LIST(Y) ; 
END; 
<ENDCODE_EXAMPLE> 
<ENDCALLOUTS> 


This example shows how you can set the number from which to begin 
numbering the callout sequence and how you can cause the callouts to 
precede the line to which they belong by using the argument PREFIX. This 
example may produce the following output: 


3] DO WHILE (*EOF); 

READ FILE(INFILE) INTO(Y); 
4] PUT LIST(Y); 

END; 


3} <CALLOUTS> 
<CODE_EXAMPLE> 
DO WHILE <CALLOUT>(9) (“EOF); 

READ FILE(INFILE) INTOCY); 
PUT <CALLOUT>(12) LIST(Y); 
END ; 

<ENDCODE_EXAMPLE> 

<ENDCALLOUTS> 


This example shows how you can place callouts inside of lines and how you 
can use an argument to the <CALLOUT> tag to control the number of the 
callout. This example may produce the following output: 


DO WHILE © (~E0F); 
READ FILE(INFILE) INTO(Y); 
put ® LIsT(y); 
END; 
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<CENTER_LINE> 


<CENTER_LINE> 


Specifies a line of text that is to be centered within the current margin. 








FORMAT <CENTER_LINE> (text [ \ { ne old 
ARGUMENTS _ text 

Specifies a line of text to be centered. 

BIGSKIP 

SMALLSKIP 


related tags 


restrictions 


required 
terminator 


Specifies a set amount of vertical space to precede the element identified as a 
line or block of text. The actual amount of space created is determined by the 
document's design. 





bd <LINE> 


° <RIGHT_LINE> 





Invalid in monospaced examples and math. 


Centered text must fit within the current text margin. If you specify text that 
is too wide, the text formatter issues a warning message, and you should 
examine your output. 





None. 


DESCRIPTION The <cCENTER_LINE> tag specifies a line of text that is to be centered within 


the current margin. 
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~“ 


<CENTER_LINE> 





EXAMPLE 


<P>Please include the following information: 


<CENTER_LINE>(Name\smallskip) 
<CENTER_LINE>(Address\bigskip) 
<CENTER_LINE>(Phone Number) 


This example may produce output like the following: 


Please include the following information: 


Name 


Address 
Phone Number 
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<CHAPTER> 


<CHAPTER> 


Begins a chapter. 





FORMAT <CHAPTER> (chapter-title [ \ symbol-name]) 





ARGUMENTS _chapter-title 


Specifies the name of the chapter. The book design may also use this 
argument in the running title. 


symbol-name 
Specifies the symbol-name to be used in all cross-references to this chapter. 


The XREF file entry for the chapter will consist of the following: 


e The value of the symbol is the number assigned to the chapter. If the 
chapter is an element in a book, the chapter number is determined based 
on the position of the chapter with respect to other chapters in the book. 


If the file being processed is not currently part of a book, the first chapter 
in the source file will be numbered 1, and additional chapters will be 
sequentially numbered thereafter. 


Symbol-names must not exceed 31 characters, and must only contain 
alphabetic letters, numbers, or underscores. Do not begin a symbol-name 
with an underscore. 





related tags / @  <REFERENCE> 





restrictions Invalid within <FRONT_MATTER> and <ENDFRONT_MATTER> . 


If the file containing this tag is to be included in a bookbuild, the symbol- 
name is required. 





required None. 
terminator 


DESCRIPTION The <cHAPTER> tag labels the beginning of a chapter. When printed, the 
chapter title and number is printed in a larger font type. VAX DOCUMENT 
automatically increments chapter numbers. 





EXAMPLE To see an example of the output that a <CHAPTER> tag produces, refer to 
the beginning of this chapter. 
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co 


<CHEAD> 


<CHEAD> 


Marks an unnumbered centered heading. Similar to the <CENTER_LINE> 
tag. 


FORMAT 


<CHEAD> (heading-text) 





ARGUMENTS 


related tags 


heading-text 
Specifies the text of the subsidiary heading. 





® <CENTER> 


<HEAD1> through <HEAD6> 














° <SUBHEAD1> 
® <SUBHEAD2> 

restrictions None. 

required None. 

terminator 

DESCRIPTION The <CHEAD> tag labels an unnumbered subsidiary heading. 
Subheadings are not numbered and do not appear in the table of contents. 
They cannot be readily used for cross-references and should be used only 
when the clarity of your exposition absolutely requires such a fine level of 
distinction. 

EXAMPLE 


<CHEAD>(How to Use the <TAG>(chead) Tag) 
<P>The use of centered headings should be restricted to occasions when the 
clarity of your exposition absolutely requires one. 


This example might produce output like the following: 


How to Use the <CHEAD> Tag 


The use of centered headings should be restricted to occasions when the 
clarity of your exposition absolutely requires one. 


<CHECK_FOR_INCLUSION> 


<CHECK_FOR_INCLUSION> 


Marks a file to ensure the file is included only once in the output. 





FORMAT 


<CHECK_FOR_INCLUSION> (file-label) 





ARGUMENTS 


related tags 


file-label 


Specifies a string that uniquely identifies this file. This string is not the 
name of the file, rather, it simply sets an internal switch to indicate that 
the following input should be read only once. The string can contain up 
to 15 alphanumeric characters or underscores and must not begin with an 
underscore character. 





None. 











restrictions This tag is conditional, and has no relationship to the structure or content of 
the document. 

required <ENDCHECK_FOR_INCLUSION> 

terminator 

DESCRIPTION The <ENDCHECK_FOR_INCLUSION> tag checks if the file containing the tag 


(the current input file) has been previously read. If it has, the rest of the file 
is ignored until the <ENDCHECK_FOR_INCLUSION> tag is found. If this is the 
first time that the file is being read, processing continues. 


An input file that contains this tag will not be processed from the point 
that the text processor finds this tag until the terminating tag is found. This 
can be useful for specifying the name of a definitions file that has already 
been processed for an entire book and does not need to be processed for an 
individual element of the book. 


You must have this terminating tag at the bottom of a file in which 
<CHECK_FOR_INCLUSION> appears. If you do not include the terminating 
tag, you might not get output after the <CHECK_FOR_INCLUSION> tag, or 
you may receive a fatal error from the tag translator when it does not find the 
specified label. 


The position of the <CHECK_FOR_INCLUSION> tag within a file is important. 
Make sure to put the tag at the very top of your file, to avoid partial 
processing of the file. Partial processing could result in illogical nesting 

of tags or other error conditions. 
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<CHECK_FOR_INCLUSION> 





EXAMPLE 


<CHECK_FOR_INCLUSION> (MY_DEFS) 


<ENDCHECK_FOR_INCLUSION> 
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This example shows how the <CHECK_FOR_INCLUSION> tag can be used to 
exclude a file (in this example, the file “MY_DEFS”) from processing during 
a bookbuild. This can be useful if the file specified contains tag definitions 
that are defined within each file as well as in the local definition file. To 
force the tag translator to process the definitions twice would be a waste of 
processing time. Instead, it is better to identify the definitions file with this 


tag and exclude the file from processing. 


<CO> 


<CO> 


Labels a callout in an example. The <CO> tag is identical to the 
<CALLOUT> tag. 





FORMAT 


<CO> /[(number)] 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


number 
Specifies the number to be used as the callout. 





e = <CALLOUT> 
e = <CALLOUTS> 
e = =<LIST> (CALLOUT) 





None. 





None. 





DESCRIPTION The <co> tag identifies a number in an example and is used within the 


<CALLOUTS> and <ENDCALLOUTS> tags. 





EXAMPLES 


See the examples in the discussion of the <CALLOUTS> tag. 


<CODE_EXAMPLE> 


<CODE_EXAMPLE> 


Begins an example of code. Code consists of words or lines of 
instructions written in a programming language or a command language. 





FORMAT 


<CODE_EXAMPLE> (code) 


or 


[KEEP] 
<CODE_EXAMPLE> [( Wine, maximumy 


code_example text 


<ENDCODE_EXAMPLE> 





ARGUMENTS 
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code 
Specifies a code fragment you want to insert into your text. 


If this argument is not specified, the terminator <ENDCODE_EXAMPLE> is 
required. 


KEEP 


Specifies that the example is not to be broken across pages, that is, if the 
example does not fit on the current page, it will be placed on the next page. 
If the example itself does not fit on a single page of output, it will be broken 
anyway. 


WIDE 


Specifies that the width of the example exceeds the document's default width 
for text. Depending on the document type, this argument can be interpreted 
as follows: 


e If the document style contains a left margin area that is normally used for 
headings, the example’s width will span that area as well as the normal 
text area. 


e If the document uses a multicolumn format, the example suspends the 
multicolumn output while the example is processed. The example will be 
output and multicolumn output is then restored. 


e If the document style provides a range of sizes and styles for examples, 
this argument may be interpreted to mean that a specific size should be 
_used for the example. 


related tags 


restrictions 


required 
terminator 


<CODE_EXAMPLE> 


MAXIMUM 


Can be used in conjunction with WIDE to indicate that the example may 
require additional adjustment to fit within the bounds of the text page. 
This argument must be used with discretion, and may not be suitable in all 
document styles. 





bg <INTERACTIVE> 


® <VALID_BREAK> 





Indexing tags (<x> and <yY> tags) are not permitted within code examples. 


Tab characters cannot be used to format code examples. You must use spaces 
rather than tabs. 


Do not use text element tags within a code_example (for example, <P>, 
<LIST> , or <NOTE> ). 





<ENDCODE_EXAMPLE> —Required if the code example is not passed as an 
argument. 


DESCRIPTION 


The code that is begun with a <CODE_EXAMPLE> tag is distinguished 
typographically in the output. The size of the example, whether it will be 
indented, and how much it will be indented from the current left margin of 
text is controlled by the document design. 


There are two types of code examples. The first is a short fragment that 
you want run in with the surrounding text. The second is one or more lines 
that you want broken out of the text that surrounds it (whether or not it is 
a “formal” example with its own number, caption, and entry in the table of 
contents). 


In the first instance, where you want the example run in with the surrounding 
text, you pass the code as an argument to the <CODE_EXAMPLE> tag. In this 
instance, you do not need a terminating tag. 


In the second instance, you should enter the code between the 
<CODE_EXAMPLE> and <ENDCODE_EXAMPLE> tags. In this context, the 
character spaces and blank lines you enter to format the code will be retained. 
Also, within this context you can use the <ELLIPSIS> tag to achieve a vertical 
ellipsis showing that you have omitted some lines of code. If your code 
example is longer than a few lines, use the <VALID_BREAK> tag to indicate 
the acceptable points for a page break. 
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<CODE_EXAMPLE> 





EXAMPLES 


<P>The <CODE_EXAMPLE>(WHILE INLOOP) statement causes the 
following block to be repeated until the <VARIABLE>(INLOOP) variable 


is set to FALSE. 


2 


<CODE_EXAMPLE> 


This example illustrates the case of a short code example that is run in with 
the surrounding text. (One other related tag is also used.) The example may 
produce the following output: 


The WHILE INLOOP statement causes the following block to be repeated until 
the INLOOP variable is set to FALSE. 


<P>The call frame is built on the stack by the following four instructions: 


PUSHAB B°SRVEXIT 
PUSHL FP 

PUSHL AP 

CLRQ - (SP) 


<ENDCODE_EXAMPLE> 


This example illustrates the use of the <CODE_EXAMPLE> tag with a longer 
example that is broken out of the surrounding text. This example may 
produce the following output: 


The call frame is built on the stack by the following four instructions: 


PUSHAB B°SRVEXIT 
PUSHL FP 

PUSHL AP 

CLRQ -(SP) 


<P>The instruction sequence listed here (patterned after code in 


module PROCSTRT) shows this second technique. 


<CODE_EXAMPLE> 


PUSHL executive-mode-PSL 
BSBB DOREI 

<ELLIPSIS> 

PUSHL user-mode-PSL 

BSBB DOREI 

<ELLIPSIS> 

DOREI: REI 


<ENDCODE_EXAMPLE> 
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This example shows a longer code example that uses the <ELLIPSIS> tag as 
well. This example may produce the following output: 


The instruction sequence listed here (patterned after code in module 
PROCSTRT) shows this second technique. 


PUSHL executive-mode-PSL 
BSBB DOREI 

PUSHL user-mode-PSL 
BSBB DOREI 

DOREI: REI 


<COMMENT> 


<COMMENT> 


Marks a portion of your SDML input file that you do not want to appear 
in your output. Text marked by a <COMMENT> tag is ignored by the tag 
translator during processing. 








FORMAT <COMMENT> (comment-text) 
or 
<COMMENT> 
comment-text 
<ENDCOMMENT> 
ARGUMENTS _ text 


related tags 
restrictions 


required 
terminator 


Specifies the text you do not want to appear in your output. 





None. 





You cannot nest <COMMENT> and <ENDCOMMENT> tags. 





<ENDCOMMENT> — Required if the text is not passed as an argument. 





DESCRIPTION 


Comments can provide useful reminders for your own use or use by writers 
who may modify your SDML file in the future. Comments can also be used 
to exclude portions of text from the output file, but that you might wish to 
save for later inclusion. The text remains in the SDML file, but does not 
appear in the output. 
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<COMMENT> 





EXAMPLE 


<CODE_EXAMPLE> 
; SECONDARY POOL COMMAND BUFFER BLOCKS 


.=0 


000000 C.CLK: .BLKW 1 ;LINK WORD 

000002 C.CTCB: .BLKW 1 ;TCB ADDRESS OF TASK TO RECEIVE COMMAND 
000004 C.CUCB: .BLKW 1 ;UCB ADDRESS IF RESPONSIBLE TERMINAL 
000006 C.CCT: .BLKW 1 ;CHARACTER COUNT, EXCLUDING TRAILING CR 
000010 C.CSTS: .BLKW 1 ;STATUS MASK 

<COMMENT> 

000012 C.CMCD: ;SYSTEM MESSAGE CODE 

000012 C.CSO: -BLKW 1 ;STARTING OFFSET OF VALID COMMAND TEXT 
<ENDCOMMENT> 


000014 C.CTR: .BLKW 1 ; TERMINATING CHARACTER 

000015 C.BLK: .BLKW 1 ;SIZE OF. PACKET IN SEC POOL (32 WD.) BLOCKS 
000016 C.CTXT: ;COMMAND TEXT, FOLLOWED BY CR 
<ENDCODE_EXAMPLE> 


This example shows a code example with comments embedded in the code. 
‘The tag translator ignores the text between the <COMMENT> tag and the 
<ENDCOMMENT> tag. This example may produce the following output: 


; SECONDARY POOL COMMAND BUFFER BLOCKS 


.=0 


000000 C.CLK: .BLKW 1 ;LINK WORD 

000002 C.CTCB: .BLKW 1 ;TCB ADDRESS OF TASK TO RECEIVE COMMAND 
000004 C.CUCB: .BLKW 1 ;UCB ADDRESS IF RESPONSIBLE TERMINAL 

000006 C.CCT: .-BLKW 1 ;CHARACTER COUNT, EXCLUDING TRAILING CR 
000010 C.CSTS: .BLKW 1 ;STATUS MASK 

000014 C.CTR: ._BLKW 1 ; TERMINATING CHARACTER 

000015 C.BLK: -BLKW 1 ;SIZE OF PACKET IN SEC POOL (32 WD.) BLOCKS 
000016 C.CTXT: ;COMMAND TEXT, FOLLOWED BY CR 
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<CONDITION> 


<CONDITION> 


Marks a section of an SDML file that is not processed unless one 
of the arguments to the tag matches the argument in the related 
<SET_CONDITION> tag. 





FORMAT 


<CONDITION> (condition-name [ \ condition-name] 
[ \ condition-name]) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


condition-name 
Specifies a condition-name created with the <SET_CONDITION> tag. 





s <SET_CONDITION> 





<CONDITION> tags cannot be nested. There must be a strict correspondence 
between <CONDITION> and <ENDCONDITION> tags. 


In monospaced examples, <CONDITION> and <ENDCONDITION> tags cannot 
occupy the same line as text for the example. 





<ENDCONDITION> — Required if the text is not passed as an argument. 


DESCRIPTION 


The <CONDITION> tag indicates that the following section of text should 
be processed only upon the condition that one of the tag’s arguments 
matches the argument in the related <SET_CONDITION> tag. If the two 
tags’ arguments are identical, the marked text is processed and included in 
the output file. If the arguments differ, the text is excluded from processing. 
The <ENDCONDITION> tag marks the end of the conditional text. 


This tag can be very useful if you must produce two or more documents 
that differ in minor ways but contain much of the same text. It is efficient to 
maintain one SDML file and identify the portions of text that are unique to 
each document. 


Before processing the SDML file, you can specify the condition-name for the 
desired document in the <SET_CONDITION> tag or in the /CONDITION 
qualifier in the DOCUMENT command line. When the tag translator 
processes the file, it includes all portions of text tagged with that condition- 
name argument and ignores all portions of text tagged with any other 
condition-name. To obtain another version of the document, simply change 
the condition-name in the argument to the <SET.CONDITION> tag, and 
reprocess the file. 


When you supply more than one condition-name argument to the 
<CONDITION> tag, only one of the condition-names need be present for 
the conditional text to be processed. . 


This is shown in the first example. 


<CONDITION> 





EXAMPLES 


J © <CONDITION> (Christmas) 
<P>Christmas, by convention, is celebrated on December 25th... 


<ENDCONDITION> 


<CONDITION> (Chanukah) 


<P>Chanukah is called the Festival of Lights... 


<ENDCONDITION> 


<CONDITION> (Wash_Bday) 
<P>Washington’s Birthday is on February 22nd... 


<ENDCONDITION> 


<CONDITION>(Christmas\Chanukah) 
<HEAD1>(Religious Holidays) 
<P>This paragragh contains general information about several religious 


holidays... 
<ENDCONDITION> 


f3 —- <SET_CONDITION> (VMS) 


When the 


This example shows how a file could be organized if you were writing about 
holidays in general, and Christmas, Chanukah, and Washington’s Birthday 
in particular. Any of three different condition states could be set at the top 
with the tag <SET_CONDITION> (Christmas), <SET-CONDITION> (Chanukah), or 
<SET_CONDITION> (Wash_Bday). The example contains four paragraphs, with 
each paragraph conditionalized differently. 


If the file is processed with <SET_CONDITION> (Christmas), the information 
on Christmas and religious holidays is processed. If the file is processed 
with <SET_CONDITION> (Chanukah), the information on Chanukah 

and religious holidays is processed. If the file is processed with 
<SET_CONDITION> (Wash_Bday), only the information on Washington’s 
birthday is processed. 


The function of the <SET_CONDITION> tag can be obtained by using the 
/CONDITION qualifier on the DOCUMENT command line instead. 


<CONDITION> (VMS) VAX/VMS<ENDCONDITION> 
<CONDITION> (RSX) RSX11M/RSX11M-PLUS<ENDCONDITION> 
command language interpreter translates the logical name... 
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This example shows how one of two clauses can be omitted from processing 
based on the condition-name specified in the <SET_CONDITION> tag. The 
section of text that is identified with <CONDITION> (VMS) would be processed 
and placed in the output file, whereas the other text would be omitted. This 
example would have the following output: 


When the VAX/VMS command language interpreter translates the logical 
name... 


<CONDITION> 


<SET_CONDITION> (RSX) 
<P>When RSX... 


<CONDITION>(VMS\RSX) 
<P>When the operating system... 


<ENDCONDITION> 
<CONDITION>(RSTS) 
<P>When RSTS ... 


<ENDCONDITION> 


This example shows how text that is applicable to the two condition-names 
“VMS” and ”RSX” can be differentiated from text that is applicable to the 
condition-name “RSTS.” By supplying both the VMS and RSX arguments to 
the first <CONDITION> tag, the writer ensures that the text will be included 
in the output if either the VMS or RSX condition-name is set. (Other text in 
the same SDML file might be conditional for only one of these condition- 
names.) 
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<CONTENTS_FILE> 


<CONTENTS_FILE> 


Specifies that the table of contents output file for a document should be 
included when the document is processed. 











FORMAT <CONTENTS_FILE> /(file-spec)] 

ARGUMENTS _file-spec 
If you place the <CONTENTS_FILE> tag in an SDML file that will be included 
in another file later, you must specify the exact file-name of the contents as 
the <CONTENTS_FILE> tag’s argument. 

restrictions <CONTENTS_FILE> is valid only within the context of front matter or within 


related tags 


required 
terminator 


a profile of a book. 





© <PROFILE> 





None. 


DESCRIPTION 


The <CONTENTS_FILE> tag specifies the position in a source file where a 
table of contents output file should be included. This tag does not produce 
a table of contents, but simply indicates placement of the contents file. A 
contents file is produced when the qualifier /CONTENTS is specified on the 
DOCUMENT command line. 


The profile tags <CONTENTS_FILE> and <INDEX_FILE> can be placed in 
either the profile of a book or in a source file. If you are creating a book (with 
a profile to be processed through a bookbuild), place these tags in the profile 
to be sure of correct placement in the output. 


A contents file always receives the filetype .DVI —device, where device is 
the type of output device you specified on the command line. For more 
information on contents generation, see Chapter 7. 


To create a table of contents from an individual file that contains a 
<CONTENTS_FILE> tag, specify the /CONTENTS quater on the command 
line. 





EXAMPLE 


To see the result of the <CONTENTS_FILE> tag, refer to the table of contents 
in this manual. The <CONTENTS_FILE> tag was placed in the profile file 
before the preface file. 


<COPYRIGHT_DATE> 


<COPYRIGHT_DATE> 


Inserts a copyright date line on the copyright page along with other 
system-specific copyright information. 





FORMAT <COPYRIGHT_DATE> (date \ owner]) 





ARGUMENTS date 


Specifies official printing date information for the book. 


owner 
Specifies the owner of the copyright. Local conventions might preclude use 
of this argument. 








restrictions The <COPYRIGHT_DATE> tag is valid only within the context of a 
<COPYRIGHT_PAGE> ... <ENDCOPYRIGHT_PAGE>. 

required None. 

terminator 





DESCRIPTION The <copyRIGHT_DATE> inserts a copyright date line on the copyright page 
along with other system-specific copyright information. 





EXAMPLE 


<Copyright_page> 
<Copyright_date>(1987\Tomato Magnates, Inc.) 
<Endcopyright_page> 


This example produces a full page of output with the following text: 


Copyright ©1987 Tomato Magnates, Inc. 
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<COPYRIGHT_PAGE> 


<COPYRIGHT_PAGE> 


Begins a copyright page and enables copyright page tags. 





FORMAT <COPYRIGHT_PAGE> 





ARGUMENTS None. 





restrictions This tag can only be used in the context of a neopy ven page and in the front 
matter of a book. 





required <ENDCOPYRIGHT_PAGE> 
terminator 


related tags © = <FRONT_MATTER> 
e = <PRINT_DATE> 


* <COPYRIGHT_DATE> 





DESCRIPTION The following copyright page tags that are enabled by <COPYRIGHT_PAGE> : 
. <PRINT_DATE> 


° <COPYRIGHT_DATE> 





EXAMPLE 


<FRONT_MATTER> (front) 
<COPYRIGHT_PAGE> 
<PRINT_DATE>(March 1987) 
<COPYRIGHT_DATE> (1987) 
<ENDCOPYRIGHT_PAGE> 
<ENDFRONT_MATTER> 


This example shows the order in which the copyright page tags are 

used. Notice that you must enable the copyright page tags within the 
<FRONT_MATTER> tag. The output of this example is a separate copyright 
page, containing the print and copyright dates, in the front matter of the 
book. 


To see an example of all the front matter tags in their correct order, refer to 
the example in the <FRONT_MATTER> tag. 


<CP> 


<CP> 


Marks the continuation of a paragraph that has been interrupted by another 
text element. 





FORMAT <CP> 





ARGUMENTS = None. 











related tags - <P> 
restrictions Invalid in math. 
required None. 
terminator 





DESCRIPTION The <p> and <cp> tags may have no visible difference in effect. In a book 
esign in which all new paragraphs begin flush left, the formatted results 
achieved by a <CP> tag and bya <P> are identical. However, in a book . 
design in which paragraphs are indented, the continued paragraph may still 
begin flush left. 


In some instances, the <CP> tag will keep text that follows a list or 
monospaced example from being “widowed” at the top of the following 
page. In other words, a continued paragraph is more closely attached to the 
text element it follows. 





EXAMPLE 


<P>Each time you log in, the system automatically executes 

two types of login command procedures: 

<LIST> (UNNUMBERED ) 

<LE>A system login command procedure 

<LE>Your personal login command procedure 

<ENDLIST> 

<CP>These login procedures are described in the following sections. 


This example may produce the following output using a book design in which 
paragraphs are indented: 


Each time you log in, the system automatically executes two types of 
login command procedures: : 


e A system login command procedure 


e Your personal login command procedure 


These login procedures are described in the following sections. 
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ol 


<CPAREN> 





<CPAREN> 


Supplies an unmatched closing parenthesis in an argument to a tag. 





FORMAT <CPAREN> 





ARGUMENTS = None. 





related tags e The following tags label other characters that must be tagged when they 
occur in an argument to a global tag: 


<AMPERSAND> 
<BACKSLASH> 
<OPAREN> 
<VBAR> 








restrictions None. 
required None. 
terminator 





DESCRIPTION The <cPAREN> tag can be used anywhere to insert a closed parenthesis 
character into text. However, it is only beneficial (in terms of keystrokes and 
control of the output) as an unmatched closing parenthesis in an argument 
passed to a tag. 


An unmatched parenthesis in an argument can cause errors when processed 
because the parentheses are used to determine the beginning and ending of 
an argument list. The <CPAREN> tag inserts the closed parenthesis character 
but is not evaluated as a closed parenthesis. 





EXAMPLE 


<SUBHEAD1>(Using a Closed Parenthesis <PARENDCHAR>(<CPAREN>) in an Argument to a Tag) 


This example may produce the following output: 


Using a Closed Parenthesis ()) in an Argument to a Tag 


Xe) 


—36 


<DATE> 


<DATE> 


Produces the current system date or time. 





FORMAT 


<DATE> /[(FULL)] 





ARGUMENTS 


related tags 


restrictions 


FULL 


Produces a full VMS date and time string in the format “dd-mmm-yyyy 
hh:mmi:ss.hh”. If this argument is not specified, only the date may be 
produced in the format “Month day, year.” (The precise format may be 
modified in different doctypes.) 





None. 





Invalid in math. 











required None. 

terminator 

DESCRIPTION The <DATE> tag produces a date that is based on the time at which the 
tag translator begins execution. Therefore, when the <DATE> (full) tag is 
specified multiple times in a source file, it always produces the same value 
and, therefore, cannot be used for timing information. 

EXAMPLES 

f])  <DATE> 


2 <DATE> (FULL) 


Example 1 produces the following output: July 20, 1987 


Example 2 produces the following output: 20-JUL-1987 10:15:35.20 
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<DEFINE_BOOK_NAME> 


<DEFINE_BOOK_NAME> 


Defines the title of a book and associates a user-defined symbol-name 
with that title for later reference. 





FORMAT 


<DEFINE_BOOK_NAME> (symbol-name \ title) 





ARGUMENTS 


related tags 


symbol-name 

Specifies the symbol that is associated with the title of the book. Symbol- 
names must not exceed 31 characters, and must only contain alphabetic 
letters, numbers, or underscores in them. Do not begin a symbol-name with 
an underscore. 


title 
Specifies the exact text of the book’s title. 





bg <DEFINE_SYMBOL> 


. <REFERENCE> 











restrictions None. 

required None. 

terminator 

DESCRIPTION The <DEFINE_BOOK_NAME> tag specifies a book’s title and adds an 
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associated user-defined symbol-name to the cross-reference file. When 
you subsequently reference this title with the <REFERENCE> tag, supplying 
the same symbol-name as an argument to <REFERENCE> , the book title is 
retrieved from the cross-reference file and is substituted for the reference. 


Depending on the document type, the title may be output with emphasized 
text (for example, italicized). . 


Note that the symbol-name argument is the first argument to the tag. In text 
element tags, the symbol-name is always the second argument. Only the 
<DEFINE_BOOK_NAME> and <DEFINE-SYMBOL> tags take a symbol-name as 
a first argument. Placing the symbol-name as the first argument to these tags 
makes it easy to keep track of your symbol-names when you list them in a 
local definitions file. All of the symbol-names will be aligned and easy to find 
in the file. 


<DEFINE_BOOK_NAME> 





EXAMPLE 


<DEF INE_BOOK_NAME>(games_book\Book of Games, Volume 2) 


This example illustrates the use of the <DEFINE_BOOK_NAME> tag for 
defining the symbol-name of the book “Book of Games” as games_book. The 
tag 9<REFERENCE> (games_book) can be used anywhere in the document to refer 
to this book name. 
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<DEFINE_SYMBOL> 


<DEFINE_SYMBOL> 


Associates a string of text with a user-defined symbol, so that the text 
can be referenced via this symbol throughout the document.. 





FORMAT 


<DEFINE_SYMBOL> (symbol-name \ text-string) 





ARGUMENTS 


related tags 


symbol-name 

Specifies the name assigned to the symbol. All symbol-names must not 
exceed 31 characters, and must only contain alphabetic letters, numbers, or 
underscores in them. Do not begin a symbol-name with an underscore. 


text-string 

Specifies the text that will be referenced via the symbol-name. Throughout 
the document, you can specify the symbol-name in the <REFERENCE> tag, 
and this text-string will be substituted for the symbol-name during processing. 





® <REFERENCE> 


° <DEFINE_BOOK_NAME> 











Note: 


restrictions None. 
required None. 
terminator 
| DESCRIPTION The <DEFINE-SYMBOL> tag specifies a string of text and associates the text 


with a user-defined symbol-name. It adds the symbol-name and the text to 
the symbol table. When you subsequently reference this text by using the 
<REFERENCE> tag and specifying the same symbol-name as its argument, the 
current value of the symbol-name is retrieved from the table and the text is 
substituted for the reference. 


For more information on the use of the symbol table, see Chapter 6. 


The symbol-name argument to the <DEFINE_SYMBOL> tag must be on the 
same line as the tag; spaces and carriage returns are significant and are 
interpreted as part of the symbol-name. 


Only the <DEFINE_SYMBOL> and <DEFINE_BOOK_NAME> tags use a symbol- 
name as a first argument. In text element tags, the symbol-name is often the 
second argument. Placing the symbol-name as the first argument to these 
tags makes it easy to keep track of your symbol-names when you list them in 
a local definitions file. All of the symbol-names will be aligned and easy to 
find in the file. 


<DEFINE_SYMBOL> 





EXAMPLE 


<define_symbol>(set_logical\RTL routine Set Logical Name, LIB$SET_LOGICAL, ) 


<P>The <REFERENCE>(set_logical) requests the calling process’s CLI to 
define or redefine a supervisor-mode logical name. 


This example shows how a phrase, “RTL routine Set Logical Name, LIB$SET_ 
LOGICAL,” can be defined as a symbol-name, “set—logical,” and then 
referenced in text by that symbol-name. By referencing the symbol-name 

in the places you want the phrase to occur, you can save keystrokes and 
ensure that you never have a typing error in that phrase. 


The example produces the following output: 


The RTL routine Set Logical Name, LIB$SET_LOGICAL, requests the calling 
process’s CLI to define or redefine a supervisor-mode logical name. 
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<DEFINITION_LIST> 





<DEFINITION_LIST> 


Begins a definition list. 





FORMAT <DEFINITION_LIST> 





ARGUMENTS = None. 





related tags ¢ = <DEFINITION_LIST_HEAD> 
e = <DEFLIST_ITEM> 


® <DEFLIST_DEF> 








restrictions None. 
required <ENDDEFINITION_LIST> 
terminator 





DESCRIPTION A definition list contains paired entries, consisting of the item being defined, 
introduced by the <DEFLIST_ITEM> tag; and the item’s definition, introduced 
by the <DEFLIST_DEF> tag. The definition list differs from a list created 
with the <LIST> tag in that the definition list items are not numbered or 
called-out in any way. 


The definition list can be given a heading with the <DEFINITION_LIST_HEAD> 
tag. Each list can contain one or more items, tagged with <DEFLIST_ITEM> , 
and each item can have a definition, tagged with <DEFLIST_DEF> . 





EXAMPLE 


<definition_list> 
<deflist_item>(Hargreaves, James) 
<deflist_def> 

d. 1778. English inventor. 
<deflist_item>(Harris, Joel Chandler) 
<deflist_def> 

1848-1908. American author. 
<deflist_item>(Harvey, William) 
<deflist_def> 

1578-1657. English physician and anatomist. 
<deflist_item>(Hauptmann, Gerhard) 
<deflist_def> 

1862-1946. German author. 
<enddefinition_list> 
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<DEFINITION_LIST> 


This example may produce the following output: 


Hargreaves, James 
d. 1778. English inventor. 


Harris, Joel Chandler 
1848-1908. American author. 


Harvey, William 
1578-1657. English physician and anatomist. 


Hauptmann, Gerhard 
1862-1946. German author. 
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<DEFINITION_LIST_HEAD > 


<DEFINITION_LIST_HEAD> 


Supplies the heading to precede a definition list. Output formatting is 
controlled by the document-type. 





FORMAT <DEFINITION_LIST_HEAD> (heading-text) 





ARGUMENTS heading-text 


Specifies the text for a heading to precede the definition list. 





related tags ¢  <DEFINITION_LIST> 
¢  <DEFLIST_ITEM> 


° <DEFLIST_DEF> 








restrictions Can be used only in the context of a <DEFINITION_LIST> tag. 
required None. 
terminator 





DESCRIPTION The <DEFINITION_LIST.HEAD> tag adds a heading to a list of defined items 
specified by the <DEFINITION_LIST> tag. 





EXAMPLE 


<definition_list> 
<definition_list_head>(Worldwide Associates) 
<deflist_item> (IAAF) 

<deflist_def> 

International Amateur Athletic Federation. 
<deflist_item> (IAEA) 

<deflist_def> 

International Atomic Energy Agency. 
<enddefinition_list> 


This example might have the following output, depending on the document 
type specified: 





WORLDWIDE IAAF 
ASSOCIATES International Amateur Athletic Federation. 
IAEA 


International Atomic Energy Agency. 
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<DEFLIST_DEF> 


<DEFLIST_DEF> 


Begins the text that defines an item in a definition list. 





FORMAT 


<DEFLIST_DEF > text 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


text 
Specifies the text of the definition. 





° <DEFINITION—LIST> 
© <DEFINITION_LIST_HEADS> 


7 <DEFLIST_ITEM> 





Can be used only in the context of a <DEFINITION_LIST> tag. 





None. 


DESCRIPTION A definition list contains paired entries, consisting of the item being defined, 


introduced by the <DEFLIST_ITEM> tag; and the item’s definition, introduced 
by the <DEFLIST_DEF> tag. 





EXAMPLE 


See the example in the discussion of the <DEFINITION_LIST> tag. 
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<DEFLIST_ITEM> 


<DEFLIST_ITEM> 


Marks an item to be defined in a definition list. 





FORMAT <DEFLIST_ITEM> (item \ item...) 





ARGUMENTS item 


Specifies the item to be defined. Up to seven items can be stacked. 





related tags © = <DEFINITION_LIST> 
e = <DEFINITION_LIST_HEADS> 


® <DEFLIST_DEF> 








restrictions Can be used only in the context of a <DEFINITION_LIST> tag. 
required <DEFLIST_DEF> . ; 
terminator 





DESCRIPTION A definition list contains paired entries, consisting of the item being defined, 
introduced by the <DEFLIST_ITEM> tag; and the item’s definition, introduced 
by the <DEFLIST_DEF> tag. 





EXAMPLE 


<definition_list> 

<deflist_item>(Hargreaves, James\d. 1778.) 
<deflist_def>English inventor. 

<deflist_item>(Harris, Joel Chandler\Born 1848.\Died 1908.) 
<deflist_def>American author. 

<deflist_item>(Harvey, William\Born 1578\Died 1657.) 
<deflist_def>English physician and anatomist. 
<enddefinition_list> 
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<DEFLIST_ITEM> 


This example may have the following output: 


Hargreaves, James 
d. 1778. 

English inventor. 

Harris, Joel Chandler 
Born 1848. 

Died 1908. 

American author. 

Harvey, William 
Born 1578 

Died 1657. 


English physician and anatomist. 
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<DOCTYPE> 


<DOCTYPE> 


Specifies the document type for your file. This tag is for informational 
purposes only. 














FORMAT <DOCTYPE> (document-type) 
ARGUMENTS document-type 

Specifies the design you want to use for your file. 
restrictions None. 
required | None. 
terminator 





DESCRIPTION The <boctTyYPE> tag specifies the document type for your file. The 


designated doctype determines how the file’s formatted output will appear. 
Each doctype follows a book design as determined by the writer and editor. 


You do not have to include the <DOCTYPE> tag in your file in order to 
process your file. You can include this tag for information purposes. You 
must specify the doctype in the DOCUMENT command line. Doing so allows 
you to process your file using different doctypes to determine which one suits 
your needs without having to modify the file. 


Table 9-1 summarizes the supported doctypes and the DOCUMENT 
command keyword names to be specified in processing these doctypes. 


Table 9-1 Supported Document Types 


Document Type 


Keyword Usage 

ARTICLE Articles 

LETTER ‘Letters or memos 

MANUAL Users’ manuals 

MILSPEC Military specifications 
OVERHEADS Overhead slides for transparencies 
REPORT General-purpose documents 


SOFTWARE User manuals containing software-specific information 


In addition, a number of the document types listed in Table 9-1 have a choice 
of designs. The design selected is specified during document processing by 
appending the design name to the document-type keyword. Table 9-2 
summarizes the key characteristics of the doctypes and their designs. 


<DOCTYPE> 


Table 9-2 Summary of Alternate Designs for Doctypes 


Keywords Size Headings' Characteristics 

ARTICLE 85 x 11 U Two columns for text 

LETTER 83 x11 U Uses full page width 

MANUAL.GUIDE 7x9 N Chapter-oriented; headings unruled 

MANUAL.PRIMER 7x9 U Chapter-oriented with sequential page numbering; 
headings unruled 

MANUAL.REFERENCE 85 x ll N Chapter-oriented; headings unruled 

MILSPEC 83 x ll N Chapter-oriented with sequential page numbering; 
two-line running headings unruled 

OVERHEADS 85 x 11 — — 

OVERHEADS.35MM 65x55 — — 

REPORT 85 x11 N Uses the full page width for text; headings are 
not ruled 

REPORT.TWOCOL 85 x 11 N Two columns for text 

SOFTWARE.BROCHURE 7x9 U Headings set in left margin, ruled 

SOFTWARE.GUIDE 7x9 N Headings set in left margin, ruled 

SOFTWARE_HANDBOOK 7x9 N Headings set in left margin, ruled 

SOFTWARE.POCKET_ 53 x7 U Headings optionally numbered or unnumbered 

REFERENCE 

SOFTWARE.REFERENCE 85 x ll N Headings set in left margin, ruled 

SOFTWARE.SPECIFICATION 85 x 11 N Headings unruled; uses full page width 


'N=numbered headings, U=unnumbered headings 





Tags unique to specific document types are summarized in the 
VAX DOCUMENT User Manual, Volume 2. 





EXAMPLE 


<DOCTYPE> (report) 


This example shows how a book’s doctype can be specified as “report.” 


Refer to VAX DOCUMENT Design Samples for examples of the output of the 
various doctypes. 
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<DOUBLE_QUOTE> 


<DOUBLE_QUOTE> 


Supplies a double quotation mark as it appears on the terminal screen. 





FORMAT 


<DOUBLE_QUOTE> 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


None. 





® <SINGLE_QUOTE> 


e° <QUOTE> 





None. 





None. 





DESCRIPTION Typesetters distinguish between opening quotation marks and closing 
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quotation marks, for example, “a quoted string.” Your terminal, on the 

other hand, has two possible characters you can use for quotation marks: 

the double quote, (") (ASCII 34) and the single quote (') (ASCII 39). In 
programming languages, a quoted string is usually delimited at each end with 
the same character, either “a quoted string," or ‘a quoted string.’ 


If you use the terminal’s double quotation mark in normal text in your SDML 
file, you get the typesetter’s closing quotation mark in the output. Thus, if 
you enter “abc” in your SDML file, you will see “abc” in your printed output. 
This is usually undesirable. 


You have two choices: 


To cause your typeset output to show a double quotation mark as it is 
shown on the terminal, use the <DOUBLE_QUOTE> tag. This is your 
most likely choice for showing examples of user input or screen displays. 


To cause your typeset output to follow typesetting conventions by using 
distinct opening and closing quotation marks, use the <QUOTE> (text) 
tag. You would use this in citing a passage from another book. 


Thus, there are very few occasions in which you press the double quote 
character on your keyboard while editing an SDML file. 


<DOUBLE_QUOTE> 





EXAMPLES 


1] <P>You can cause the translation of a symbol by using a double 
quotation mark (<DOUBLE_QUOTE>) directly in front of it. 


This example shows the use of the <DOUBLE_QUOTE> tag. It may produce 
the following output: 


You can cause the translation of a symbol by using a double quotation mark 
(") directly in front of it. 


2 <P>You can cause the translation of a symbol by using a double 
quotation mark (") directly in front of it. 


This example shows what your output would be like without using the tag, 
but just entering the character from the keyboard. 


You can cause the translation of a symbol by using a double quotation mark 
(”) directly in front of it. 
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<ELEMENT> 


<ELEMENT > 


Identifies a file that contains an element of a book. 





FORMAT 


<ELEMENT > (file-spec) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


file-spec 
Specifies a file. The file type must be supplied. 





® <PROFILE> 


e <INCLUDES_FILE> 





Must be used in the context of a profile. 





None. 





DESCRIPTION 


A profile of a book is required in order to build (process) a book. A book’s 
profile contains an ordered list of the elements that comprise the book. In 
the profile, you label each of these elements with an <ELEMENT> tag. Only 
those files listed with <ELEMENT> tags are included in the book during the 
bookbuild. They should be listed in the profile in the order in which they are 
presented in the book. 


A file specified as an element must begin with one of the following tags: 


: <APPENDIX> 


<CHAPTER> 


<FRONT MATTER> 


<GLOSSARY > 


<PART> 


For more information on creating a profile and bookbuilding, see Chapter 4. 





EXAMPLE 


_ Assume that a writer is writing a book that contains several chapters and that 


one of the chapters is the file My_Intro_Chap.SDML. At the top of this file is 
included the tag: <CHAPTER> (Introduction\intro_chap). 


Along with the other <ELEMENT> tags for this book, the profile for this book 
would then contain the following: 


<ELEMENT> (My_Intro_Chap.SDML) 


<ELLIPSIS> 


<ELLIPSIS> 


Supplies vertical ellipsis points to show omitted material in text and tables. 





FORMAT  <ELLIPSIS> 





ARGUMENTS None. 











related tags e  <HELLIPSIS> 
restrictions Invalid in math. 
required None. 
terminator 





DESCRIPTION The <ELLirsis> tag supplies vertical ellipsis points to show omitted material 
in text and tables. The vertical ellipsis is positioned with respect to the current 
left margin. 





EXAMPLE 


<P>The instruction sequence listed here (patterned after code in 
module PROCSTRT) shows this second technique. 
<CODE_EXAMPLE> 


PUSHL executive-mode-PSL 
BSBB DOREI 

<ELLIPSIS> 

PUSHL user-mode-PSL 

BSBB DOREI 

<ELLIPSIS> 

DORET: REI 

<ELLIPSIS> 


<ENDCODE_EXAMPLE> 
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if) 


<ELLIPSIS> 


This example may produce the following output: 


The instruction sequence listed here (patterned after code in module 
PROCSTRT) shows this second technique. 


PUSHL executive-mode-PSL 
BSBB DOREI 


PUSHL user~mode-PSL 
BSBB DOREI 


DORET: REI 
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<EMPHASIS> 


<EMPHASIS> 


Marks a word or phrase for distinctive typographical treatment. 





FORMAT \ BOLD 
\ ITALIC 
<EMPHASIS > (text \ SMALLCAPS ) 
\ SMALL__BOLDCAPS 


ARGUMENTS) TEXT 


Specifies the text to be emphasized. 


BOLD 
Indicates that the text should be set in a boldface font, rather than the default 
italic. 


ITALIC 


Indicates that the text should be set in the current italic font. This is the 
default. 


SMALLCAPS 


Indicates that the text is to be set in small capital letters. 


SMALL_BOLDCAPS 


Indicates that the text is to be set in small capital letters. 








related tags ° = <QUOTE> 
° = <UNDERLINE> 








restrictions None. 
required None. 
terminator 





DESCRIPTION The default form of emphasis is to set the text in an italic font. Use one of 
the optional keyword arguments to change the emphasis to another font. 
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ol 


<EMPHASIS> 





EXAMPLE 


<P>An <EMPHASIS>(overuse) of the <TAG>(emphasis) tag 
<EMPHASIS>(inevitably\bold) <EMPHASIS>(reduces\small_boldcaps) its 
<EMPHASIS>(smallcaps) (effectiveness) . 


This example may produce the following output: 


An overuse of the <EMPHASIS> tag inevitably REDUCES its EFFECTIVENESS. 
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<ENDCOPYRIGHT_PAGE> 


<ENDCOPYRIGHT_PAGE> 


Terminates the copyright page and optionally provides text that may be 
used on a document-type specific basis. 





FORMAT <ENDCOPYRIGHT_PAGE> [(identification)] 





ARGUMENTS _ identification 


Is a local convention for information to be supplied on the copyright page. 








restrictions This tag can only be used in the context of a copyright page. 
required None. 
terminator 





DESCRIPTION The <ENDCOPYRIGHT_PAGE> terminates the copyright page and epaenally 
provides text that may be used on a document- type specific basis. 





EXAMPLE 


<FRONT_MATTER> (front) 
<COPYRIGHT_PAGE> 
<PRINT_DATE>(March 1987) 
<COPYRIGHT_DATE> (1987) 
<ENDCOPYRIGHT_PAGE> 
<ENDFRONT_MATTER> 


This example shows the order in which the copyright page tags are 

used. Notice that you must enable the copyright page tags within the 
<FRONT_MATTER> tag. The output of this example is a separate copyright 
page in the front matter of the book, and the page contains the print and 
copyright dates. 


To see an example of all the front matter tags in their correct order, refer to 
the example in the <FRONT_MATTER> tag. 


<ENDPART_PAGE> 


<ENDPART_PAGE> 


Terminates a part page and optionally specifies paging attributes for text 
that follows. 





FORMAT | <ENDPART_PAGE> /(RENUMBER)] 





ARGUMENTS RENUMBER 
Specifies that the part page is to be numbered 1. If this argument is not 
specified, page numbering continues following the partpage with the next 
odd-numbered page. 








restrictions This tag must be used in the context of a part page. 
required None. 
terminator 





DESCRIPTION The <ENDPART_PAGE> tag terminates a part page and optionally specifies 
paging attributes for text that follows. 


<ENDTITLE_PAGE> 


<ENDTITLE_PAGE> 


Terminates a title page and optionally ppecinee text to appear at the 
bottom of the title page. 





FORMAT <ENDTITLE_PAGE> (text) 





ARGUMENTS _ text 


Specifies a line to appear at the bottom of the title page. 








restrictions The <ENDTITLEPAGE> tag is valid only within the context of a title page. 
required None. 
terminator 





DESCRIPTION The <ENDTITLE_PAGE> tag terminates a title page and optionally specifies -: 
text to appear at the bottom of the title page. ; 





EXAM PLE Because the <ENDTITLE_PAGE> tag only terminates the title page, refer to the 
title page of this manual for an example of title page output. 
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<EXAMPLE> 


<EXAMPLE> 


Labels the beginning of a formal example. 





FORMAT 


<EXAMPLE> (example-caption[ \ symbol-name)]) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


example-caption 

Specifies the text of the caption to be associated with the example, if any. 
The example caption and the associated example number will be written to 
the table of contents for the document. 


symbol-name | 

Specifies the symbolic identifier to be associated with the example. The 
symbol identifier will be assigned a numeric value, which will be the current 
example number. The symbol and its value are placed in the symbol table. 


Symbol-names must not exceed 31 characters, and must only contain 
alphabetic letters, numbers, or underscores. Do not begin a symbol-name 
with an underscore. 





e <CODE_EXAMPLE> 


<EXAMPLE_ATTRIBUTES> 


<EXAMPLE_FILE> 


<EXAMPLE_SPACE> 


<INTERACTIVE> 


<VALID_BREAK> 





Cannot contain <TABLE>, <FIGURE>, or <MATH> tags. 





<ENDEXAMPLE> 





DESCRIPTION The <EXAMPLE> tag begins an example. 
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If the body of the example spans more than a single page of text, the example 
caption is repeated on each page on which the example continues. 


If the example is more than a page, page breaks are handled automatically 

by the text processor. You can control the page breaking by using <PAGE> 
tags to specify explicit page breaks, or <VALID_BREAK> tags to specify good 
breaking points. 


Note that the presence of the symbol-name argument and the example- 
caption argument indicate that the example is a formal, numbered example. 


<EXAMPLE> 





EXAMPLE 


<EXAMPLE>(VAXcluster Multi-file Summary\multi_file_exam) 
<EXAMPLE_ATTRIBUTES> (WIDE) 
<EXAMPLE_FILE>(monitor_multi_file_summary) 


<ENDEXAMPLE> 


This example illustrates a one-page example, which uses the WIDE argument 
of the <EXAMPLE_ATTRIBUTE> tag. Assume that this example is the first 
example in the fourth chapter. 


The contents of the example are included using the <EXAMPLE_FILE> tag. 
The file that is included must contain either a code example or interactive 


example: 


This example may produce the following output: 


Example x—x VAXcluster Multi-file Summary 





° Node: 
From: 15- 


To: 15- 


Interrupt Stack 
Kernel Mode 
Executive Mode 
Supervisor Mode 
User Mode 
Compatibility Mode 
Idle Time 


Node: 
From: 15- 
To: 15- 


Fault Rate 
Read Rate 

Read I/O Rate 
Write Rate 
Write I/O Rate 


Page 
Page 
Page 
Page 
Page 


Free List Fault Rate 


Modified List Fault Rate 


Demand Zero Fault Rate 
Global Valid Fault Rat 
Wrt In Progress Fault 
System Fault Rate 


Free List Size 
Modified List Size 


VAX/VMS Monitor Utility 
TIME IN PROCESSOR MODES 
MULTI-FILE SUMMARY 


MOE 
APR-1984 18:17 


CURLEY 
15-APR-1984 18:17 


APR-1984 20:17 15-APR-1984 20:17 


6.51 0.50 
25.73 0.42 
9.46 0.95 
1.97 0.00 
13.24 5.33 
0.00 0.07 
23.61 0.02 
VAX/VMS Monitor Utility 
PAGE MANAGEMENT STATISTICS 
MULTI-FILE SUMMARY 
MOE CURLEY 
APR-1984 18:17 15-APR-1984 18:17 


APR-1984 20:17 15-APR-1984 20:17 
36.73 8.81 

14.28 4.71 

1.20 0.70 

0.00 0.00 

0.00 0.00 

8.60 1.40 

5.83 2.29 

12.96 1.68 

e 8.10 2.69 
Rate 0.00 0.00 
; 4.92 0.53 
7586 . 30 8630.14 

87.69 324.07 


LARRY 


15-APR-1984 18: 
15-APR-1984 20: 


6. 
12. 
1. 
0. 
56. 
0. 
92. 


LARRY 


15-APR-1984 18: 
15-APR-1984 20: 


9665. 
32. 


ooococjo oooo°o 


2 
B 


ob 
oOoOrOD 


ON ROWDKHN DOO 


Row 


Average 


4. 


bo al 
aororRND 


w 


Row 


YOON 


4 


Average 


he 
rFOW BND Ww ooooan 


ies] 
Q 
N 
~ 


147. 


DOMONK COBwWW 


Row Row 
Minimum Maximum 
0.50 6.51 
0.42 25.73 
0.95 9.46 
0.00 1.97 
5.33 56.14 
0.00 0.07 
0.02 92.63 

Row Row 
Minimum Maximum 
0.49 36.73 
0.00 14.28 
0.00 1.20 
0.00 0.00 
0.00 0.00 
0.24 8.60 
0.00 5.83 
0.24 12.96 
0.00 8.10 
0.00 0.00 
0.18 4.92 
7586.30 9665.06 
32.12 324.07 
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<EXAMPLE_ATTRIBUTES> 


<EXAMPLE_ATTRIBUTES> 


Specifies attributes for the current example. 








FORMAT MULTIPAGE 
<EXAMPLE_ATTRIBUTES> (| KEEP 
FLOAT 
[\ WIDE}) 
ARGUMENTS MULTIPAGE 
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Specifies that the example has multiple elements, and that each element is 
allowed to break at the start of a new page. This argument is required if the 
example will be on more than one page. When an example is continued, the 
example caption is automatically repeated at the beginning of each new page 
of output. 


KEEP 


Specifies whether the example is to be kept with the text that immediately 
precedes it. 


FLOAT 


Specifies whether the location of a one-page example is allowed to float. 
FLOAT indicates that if there is not enough room on the current page for the 
example, the text processor will fill the current page with the text from the 
source file that follows the <EXAMPLE> tag sequence, and place the example 
at the top of the next page of output. 


Float is the default for an example that has a caption and does not specify 
MULTIPAGE or KEEP. 


WIDE 


Specifies that the width of the example exceeds the document's default width 
for text. Depending on the doctype, this argument can be interpreted as 
follows: 


e If the document style contains a left margin area that is normally used for 
headings, the example’s width will span that area as well as the normal 
text area. 


e If the document uses a multicolumn format, the example suspends 
multicolumn output while the example is processed. The example is 
output and the multicolumn output is then restored. 


e If the document style provides a range of sizes and styles for examples, 
this argument can be interpreted to mean that a specific size should be 
used for the example. 


related tags 


<EXAMPLE_ATTRIBUTES> 





e <EXAMPLE> 
e <EXAMPLE_FILE> 


° <EXAMPLE_SPACE> 














restrictions Must be enabled by <EXAMPLE> . 

required None. 

terminator 

DESCRIPTION By default, if an example does not fit on the current output page, it is placed 
at the top of the next page. The text that follows the example in the SDML 
file is used to fill the current output page. Thus, the example’s position in the 
text may change. It is said to “float.” 
If the example will be longer than a page, use the MULTIPAGE argument. 
The presence of the MULTIPAGE argument indicates that the example 
requires more than one page of output. The example will not be allowed to 
float. 

EXAMPLE 


<EXAMPLE> (Command Procedure for Adding a User\adduserex) 
<EXAMPLE_ATTRIBUTES> (WIDE\MULTIPAGE) 


<CODE_EXAMPLE> (WIDE) 
$! 


$ !  ADDUSER.COM -- Adds a new user to the system authorization file 


A 


USERDISK = "WRKD$:" 
UAF = "$AUTHORIZE" 


SET DEFAULT SYS$SYSTEM 
! 


PRRAHAHHHHAHAHAHHASHH 


SET TERMINAL/NOECHO 


! Default disk for new users 


ON CONTROLY THEN GOTO CLEANUP 

ON WARNING THEN GOTO CLEANUP 

OLDDIR = F$LOGICAL("SYS$DISK") + F$DIRECTORY ()’ 
PREVPRIV = F$SETPRV("SYSPRV") 

IF .NOT. F$PRIVILEGE("SYSPRV") THEN GOTO NOPRIV 


! Request account information 


INQUIRE USERNAME "Username" 
INQUIRE FULLNAME "Full name" 


$ INQUIRE PASSWORD "Password [’’Username’]" 


$ SET TERMINAL/ECHO 


$ IF PASSWORD .EQS. "" THEN PASSWORD = USERNAME 


<VALID_BREAK> 
$GET_GRP: 


$ INQUIRE GRP "UIC Group Number" 
$ IF GRP .EQS. "" THEN GRP = "x" 


$ WRITE SYS$OUTPUT "" 


$ WRITE SYS$OUTPUT "Determine the UIC from the following listing:" 


$ WRITE SYS$QUTPUT "" 


$ UAF SHOW [’GRP’ ,*]/BRIEF 


$ INQUIRE UIC 


$ IF UIC .EQS. "" THEN GOTO GET_GRP 
$ IF F$LOCATE("[",UIC) .EQ. F$LENGTH(UIC) .AND. - 

F$LOCATE("<",UIC) .EQ. F$LENGTH(UIC) THEN UIC = "[" + UIC + "]" 
$ INQUIRE ACCOUNT "Account Name [VMS]" 
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<EXAMPLE_ATTRIBUTES> 


$ IF ACCOUNT .EQS. "" THEN ACCOUNT = "VMS" 

$ INQUIRE PRIVS "Privileges [NONE] " 

$ IF PRIVS .NES. "" THEN PRIVS = "/PRIV=(" + PRIVS + ")" 
$ USERDIR = F$EXTRACT(0,9, USERNAME) 

$ INQUIRE TMP "Login Directory [’’USERDIR’]" 

$ IF TMP .NES. "" THEN USERDIR = TMP 

$ INQUIRE TMP "Login Device [’’USERDISK’]" 

$ IF TMP .NES. "" THEN USERDISK = TMP 

$ DQUOTA = 0 

$ IF F$SEARCH("’ ’USERDISK’[0,0]QUOTA.SYS") .EQS. "" THEN GOTO NQO 
$ DQUOTA = 1 

<VALID_BREAK> 

$ ! 

$ ! Restore prior working environment 

$! 

$CLEANUP : 


$ SET TERMINAL/ECHO 

$ PREVPRIV = F$SETPRV(PREVPRIV) 

$ SET DEFAULT ’OLDDIR’ 

$ EXIT 

$! 

$ ! In case proper privileges are not set 

$ ! 

s$NOPRIV: . 
$ WRITE SYS$OUTPUT "You need SETPRV or SYSPRV privilege to run this procedure" 
$ GOTO CLEANUP 

<ENDCODE_EXAMPLE> 

<ENDEXAMPLE> 


This example illustrates the use of the <MULTIPAGE> argument. Two points 
especially should be noted: 


e The <VALID_BREAK> tags in the <CODE_EXAMPLE> provide the text 
formatter with information about suitable places to break pages. 


e Because the example is wide, the WIDE argument was specified not only 
for the <EXAMPLE> tag, but also for the <CODE_EXAMPLE> tag within 
the example. 


This example may produce the following output. 
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<EXAMPLE_ATTRIBUTES> 


Example x—x Command Procedure for Adding a User 





ADDUSER.COM -- Adds a new user to the system authorization file 


$1 

$ ! 

$ ! 

$ USERDISK = "WRKD$:" ! Default disk for new users 
$ UAF = "$AUTHORIZE" 

$ ON CONTROLY THEN GOTO CLEANUP 

$ ON WARNING THEN GOTO CLEANUP 

$ OLDDIR = F$LOGICAL("SYS$DISK") + F$DIRECTORY()’ 

$ PREVPRIV = F$SETPRV("SYSPRV") 

$ IF .NOT. F$PRIVILEGE("SYSPRV") THEN GOTO NOPRIV 

$ SET DEFAULT SYS$SYSTEM 

$ 
$ 
$ 
$ 


Request account information 


! 
1 
! 
INQUIRE USERNAME "Username" 
$ INQUIRE FULLNAME "Full name" 
$ SET TERMINAL/NOECHO 
$ INQUIRE PASSWORD "Password [’’Username’]" 
$ SET TERMINAL/ECHO 
$ IF PASSWORD .EQS. "" THEN PASSWORD = USERNAME 
$GET_GRP: 
$ INQUIRE GRP "UIC Group Number" 
$ IF GRP .EQS. "" THEN GRP = "x«" 
$ WRITE SYS$OUTPUT "" 
$ WRITE SYS$OUTPUT "Determine the UIC from the following listing:" 
$ WRITE SYS$OUTPUT "" 
$ UAF SHOW [’GRP’,*]/BRIEF 
$ INQUIRE UIC 
$ IF UIC .EQS. "" THEN GOTO GET_GRP 
$ IF F$LOCATE("[",UIC) .EQ. F$LENGTH(UIC) .AND. - 
F$LOCATE("<",UIC) .EQ. F$LENGTH(UIC) THEN UIC = "({" + UIC + "]" 
$ INQUIRE ACCOUNT “Account Name [VMS]" 
$ IF ACCOUNT .EQS. "" THEN ACCOUNT = "VMS" 
$ INQUIRE PRIVS "Privileges [NONE]" 
$ IF PRIVS .NES. "" THEN PRIVS = "/PRIV=(" + PRIVS + ")" 
$ USERDIR = F$EXTRACT(O,9,USERNAME) 
$ INQUIRE TMP "Login Directory [? °USERDIR’]" 
$ IF TMP .NES. "" THEN USERDIR = TMP 
$ INQUIRE TMP "Login Device [’’USERDISK’]" 
$ IF TMP .NES. "" THEN USERDISK = TMP 
$ 
$ 


DQUOTA = 0 
IF F$SEARCH("’?USERDISK’ [0,0]QUOTA.SYS") .EQS. "" THEN GOTO NQO 
$ DQUOTA = 
$ | 
$ ! Restore prior working environment 
$ ! 
$CLEANUP : 


$ SET TERMINAL/ECHO 

$ PREVPRIV = F$SETPRV(PREVPRIV) 

$ SET DEFAULT ’OLDDIR’ 

$ EXIT 

$.! 

$ ! In case proper privileges are not set 
$ ! 

$NOPRIV: 


$ WRITE SYS$OUTPUT "You need SETPRV or SYSPRV privilege to run this procedure" 


$ GOTO CLEANUP 
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<EXAMPLE_FILE> 


<EXAMPLE_FILE> 


Causes a separate file containing an example to be included in the source 
file. 





FORMAT 


<EXAMPLE_FILE> (file-spec) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


file-spec 


Specifies the file containing the example. 





° <EXAMPLE> 
° <EXAMPLE_SPACE> 


. <EXAMPLE_ATTRIBUTES> 





Cannot be used in an argument to a tag. 





None. 





DESCRIPTION 


The <EXAMPLE_FILE> tag causes the entire contents of the file to be included 
at this point in the SDML file. (It is identical in action to the <INCLUDE> 


tag.) 


The included file should be an SDML file containing a complete coded 
example, perhaps using <CODE_EXAMPLE> or <INTERACTIVE> tags. If the 
<EXAMPLE> tag specifies the WIDE argument, the included file must specify 
the WIDE argument on the appropriate tags. For more information on correct 
coding of examples and example files, including how to specify valid breaks, 
see Chapter 3. 


The <EXAMPLE_FILE> tag may have a logical name for an argument. The 
logical name can be defined by first entering an <INCLUDES_FILE> tag in the 
profile. The information in that tag is used to make the proper logical name 
assignment during processing. 





EXAMPLE 


See the example in the discussion of the <EXAMPLE> tag. 


<EXAMPLE_SPACE> 





<EXAMPLE_SPACE> 


Leaves space for an example that will be pasted in during final production. 





FORMAT value 
MPLE_ > 
<EXAMPLE_SPACE> /( es Pe [\ text) 





ARGUMENTS _ value 
Specifies the size of the space in picas, a scale used by typesetters. There are 
approximately 6 picas to the inch. Thus, if the example is 4 inches high, you 
should specify 24 picas. The value must not exceed page depth limitations for 
the current document design. If you omit the value, a default value of 2 picas 
is used. 


FULL_PAGE 


If you specify the keyword FULL_PAGE, a full blank page is reserved for the 
example. 


text 
Specifies text to be printed in the center of the space. (For example, an art file 
number, a file name that contains the example, or some other note.) 








related tags ¢ = <EXAMPLE> 
@ = <EXAMPLE_FILE> 
e _<EXAMPLE_ATTRIBUTES> 
e <.REFERENCE> 
restrictions | Can be used only in the context of an <EXAMPLE> tag. The value must not 


exceed page-depth limitations. 





required None. 
terminator 





DESCRIPTION The <EXAMPLE_SPACE> tag causes vertical space to be left on the output 
page for an example that will be pasted in by hand during final production. 
Any text supplied as the second argument is printed in the center of the 
space. 
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~J 


<EXAMPLE_SPACE> 





EXAMPLE 


<EXAMPLE> (Completing Form DD-214\annotated_dd214_exam) 
<EXAMPLE_ATTRIBUTES> (wide) 

<EXAMPLE_SPACE>(12\Photo-reduced copy of the end of DD-214 here.) 
<ENDEXAMPLE> 


This example may produce the following output: 


Example x—-x Completing Form DD-214 


Photo-reduced copy of the end of DD-214 here. 
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<FCMD> 


<FCMD> 


Specifies the keyword portion of a formatted command/parameter pair in 
a format section. 





FORMAT 


<FCMD> (keyword-part/ \ parameter-list}) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


keyword-part 


Specifies the keyword portion of the keyword/parameter pair. 


parameter-list 
Lists the command parameters, if any. 


Parameters specified in this argument will differ on output from arguments 
specified using <FPARMS>. If you do specify <FCMD> with a null second 
argument, it is recommended that you explicitly declare the absence of 
parameters using <FPARMS> as follows: 


<FCMD>(KEYWORD-PART) <FPARMS>() 


If you do not specify a second argument, and if <FPARMS> is not specified, 
SDML will issue a warning message that it has no explicit declaration of 
parameters. 





7 <FORMAT> 
® <FPARM> 


s <FPARMS> 





Enabled only within the context of the <FORMAT> tag. 





None. 


DESCRIPTION 


The <FCMD> tag identifies a command or keyword within a format section. 
You can specify the command or keyword’s argument list as the second 
argument to this tag. The <FCMD> tag should be used only in the context 
of a format section. A format section is established by <FORMAT> and 
<ENDFORMAT> . 


If the parameter-list argument text does not fit on one line, the text formatter 
chooses suitable line breaks based on the presence of spaces. 
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<FCMD> 

















EXAMPLES 
f] = <Format> 
<FCMD>(exit) <FPARMS>() 
<ENDFORMAT> 
Specifies a single command keyword. <FPARMS> is explicitly specified as 
null. The output from this code fragment is shown in Output Sample 1. 
F] = <FORMAT> 
<FCMD>(append) <FPARMS>(input-file-spec output-file-spec) 
<ENDFORMAT 
This example specifies the command keyword and its parameters using both 
the <FCMD> and <FPARMS> tags. The output that this example produces is 
shown in Output Sample 2. 
Notice the difference between Output Sample 2 and 3. In Sample 2, space is 
left between the command-keyword and the parameter-list. In Sample 3, no 
space is left. This formatting is produced by the syntax used in the <FCMD> 
command. 
K] | <FORMAT> 
<FCMD> (f$element\ (element-number , delimiter, string) ) 
<ENDFORMAT 
This example specifies both the command-keyword and the parameter-list 
arguments to the <FCMD> tag. The output that this example produces is 
shown in Output Sample 3. 
@)  <FORMAT> 
<FCMD>(set protection\ [=code] <keyword>(/DEFAULT) ) 
<ENDFORMAT 
This example illustrates how to control the interpretation of keywords tagged 
with the global <KEYWORD> tag when they are mixed in with the parameter 
list of a format specification. The output that this example produces is shown 
in Output Sample 4. 
OUTPUT exit 
SAMPLE 1 
OUTPUT append input-file-spec output-file-spec 
SAMPLE 2 
OUTPUT f$element(element-number, delimiter, string) 
SAMPLE3  - 
OUTPUT set protection/=code]/DEFAULT 
SAMPLE 4 
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<FIGURE> 


<FIGURE> 


Labels the beginning of a figure. 





FORMAT 


<FIGURE> (figure-caption \ [symbol-name]) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


figure-caption 

Specifies the text of the caption to be associated with the figure. The figure- 
caption and the associated figure number will be written to the table of 
contents for the document. 


symbol-name 

Specifies the symbolic identifier to be associated with the example. The 
symbol-name is assigned a numeric value which becomes the current figure 
number. The symbol-name and its value are placed in the symbol table. 


All symbol-names must not exceed 31 characters, and must only contain 
alphabetic letters, numbers, or underscores in them. Do not begin a symbol- 
name with an underscore. 





© <FIGURE—ATTRIBUTES> 


bs <FIGURE_FILE> 


<FIGURE_SPACE> 


<LINE_ART> 


<REFERENCE> 


<ICON> 


<ICON-__FILE> 





None. 





<ENDFIGURE> 


DESCRIPTION 


The <FIGURE> tag is used to label formal and informal figures. A formal 
figure is listed in the table of contents, has a unique number by which it is 
cross-referenced from other parts of your book, and has a caption that labels 
it. An informal figure does not appear in the Table of Contents and has no 
caption or number identifier. 


The presence of a figure-caption and symbol-name indicates that the figure is 
a formal, numbered figure. 


9-71 


<FIGURE> 


The figure-caption argument of this tag specifies the text of the caption 
associated with the figure. The figure caption and the associated figure 
number will be written to the table of contents for the document. If the 
body of the figure spans more than a single page of text, the figure caption is 
repeated on each page on which the figure continues. 


The symbol-name specifies the symbolic identifier to be associated with the 
figure. The symbol identifier will be assigned a numeric value, which will be 
the current figure number. The symbol and its value are placed in the symbol 
table. 


A formal figure is sometimes long. If you think one of your figures 
will be longer than a page, label it as a multipage figure in the 
<FIGURE_ATTRIBUTES> tag. 


If the figure does not fit on the current output page, the figure is placed at 
the top of the next page. The text that follows the example in the SDML file 
is used to fill the current output page. Thus, the figure’s position in the text 
may change; it is said to “float.” If floating is undesirable you must use the 
KEEP argument to fix the figure at its current position in the text. If it does 
not fit on the page, the page is terminated, and the figure begins on a new 
page. Use of KEEP ensures that the figure and its accompanying text remain 
in the same order. However, KEEP should be used sparingly and only where 
examples are short and frequent, in order to avoid excessively short pages. 





EXAMPLES 


<FIGURE>(Example of Terminal-Created Art\transfer_vector_exam) 
<FIGURE_ATTRIBUTES> (KEEP) 
<LINE_ART> (KEEP) 


Shareable Image Executable Image 
t----------- + t------------ + 
+----| Vector A |<------- + | 
J teeeen------ + | | ae, 
| -#e=(Vector-B|S=-st terse Invoke A | 
| | #----------- + | | 
+--->| 1 | A 
| | Routine A | tocecccHo- Invoke B_~ | 
| | | 
|) Oe Retere oe - | | 
+->| | 5 catetahetetetetetentateatel + 
| Routine B | 
| 
+----------- + 


<ENDLINE_ART> 
<ENDF IGURE> 


In this example, the <FIGURE_ATTRIBUTES> tag contains a KEEP argument, 
to specify that the figure should be kept with the immediately preceding text. 
The <LINE_ART> tag also has a KEEP argument, to specify that the figure 
should not break across pages. 


The figures you are able to create using your terminal keyboard may be 
adequate for draft purposes, but will not be acceptable in the context of 
typeset output. 
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<FIGURE> 


This example may produce the following output: 


Figure x—x Example of Terminal-Created Art 


Shareable Image Executable Image 
t----------- + +--------- =e + 
+->>>) Vector A. | <==-5>-> + | | 
[0 te-n-e---=-- + 2 . | 
| +--] Vector B |<---+  +----- Invoke A | 
jl) eeeeereeten + | | | 
ee=>| | | | : | 
| | Routine A | eae Invoke B_ | 
| | | | | 
J teeeennnne-- + | ; | 
+->| | +------------ + 
| Routine B | 
| | 
to----------- + 





<DEF INE_SYMBOL> (ZK_2347\2) 

<FIGURE>(Illustration of the Workshop Layout Showing Forklift\ZK_2347) 
<FIGURE_SPACE>(FULL_PAGE\An illustration of the memory management workshop 
analogy, complete with picture of the forklift.) 

<ENDFIGURE> 


This example illustrates how to code a figure that will take one page. This 
example may produce output like that found on the following page. 
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<FIGURE> 


Figure x—x Illustration of the Workshop Layout Showing Forklift 


An illustration of the memory management workshop 
analog complete with picture of the forklift. 
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<FIGURE> 


<FIGURE>(Discreet Portions of the Process Header\proc_head_fig) 
<FIGURE_ATTRIBUTES> (Multi page) 

<FIGURE_SPACE>(15\Shows general structure of process header) 
<FIGURE_SPACE>(15\Shows structure of process page tables) 

<ENDF IGURE> 


This example shows how to code a figure that is allowed to extend over 


several pages. The MULTIPAGE argument to the <FIGURE_ATTRIBUTES> tag 
tells the text formatter that the figure is more than one page. 
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<FIGURE> 


Figure x—x Discrete Portions of the Process Header 


Shows general structure of process header 


Figure x—x Cont'd. on next page 
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<FIGURE> 


Figure x—-x (Cont.) Discrete Portions of the Process Header 


Shows structure of process page tables 
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<FIGURE> 


Zi <p> ... and then proceeds to linking the object 
modules into an executable image. (You are not required to 
put object modules in a library. You can link them directly.) The following 
figure illustrates the implementation cycle. 


<FIGURE> 

<F IGURE_SPACE> (17\ZK~--8769--84) 
<ENDF IGURE> 

<P> 

The first cycle shows that 


This example shows how to code an informal figure that appears within text 
without floating, without a number, and without a caption. It may produce 
the following output: 


. and then proceeds to linking the object modules into an executable image. 
(You are not required to put object modules in a library. You can link them 
directly.) The following figure illustrates the implementation cycle. 


ZK-8769-84 


The first cycle shows that... 
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<FIGURE_ATTRIBUTES> 


<FIGURE_ATTRIBUTES> 


Specifies the placement of a figure on the page. Also specifies valid page 
breaks for that figure. 








FORMAT MUL TIPAGE 
<FIGURE_ATTRIBUTES> ( | KEFpP 
FLOAT 
[\ WIDE) 
ARGUMENTS MULTIPAGE 


Specifies that the figure has multiple elements, and that each element is 
allowed to break at the start of a new page. This argument is required if the 
figure will be on more than one page. When a figure is continued, the figure 
caption and figure column heads, if any, are automatically repeated at the 
beginning of each new page of output. 


KEEP | 


Specifies that the figure is to be kept with the immediately preceding text. 
This is the default for a figure without a caption. 


FLOAT 


Specifies whether the location of a one page figure is allowed to float. FLOAT 
indicates that if there is not enough room on the current page for the figure, 
the text processor will fill the current page with the text from the source file 
that follows the <FIGURE> tag sequence, and place the figure at the top of 
the next page of output. 


Float is the default for a figure that has a caption and does not specify 
MULTIPAGE or KEEP. 


WIDE 


Specifies that the width of the figure exceeds the document’s default width 
for text. Depending on the document type, this argument can be interpreted 
as follows: 


e If the document style contains a left margin area that is normally used for 
headings, the figure’s width will span that area as well as the normal text 
area. 


e If the document uses a multicolumn format, the figure suspends 
multicolumn output while the figure is processed. The figure is output 
and multicolumn output is then restored. 


e If the document style provides a range of sizes and styles for figures, this 
argument may be interpreted to mean that a specific size should be use 
for the figure. Ms 


<FIGURE_ATTRIBUTES> 


related tags 


restrictions 


required 
terminator 





* <FIGURE> 
° <FIGURE_FILE> 


ad <FIGURE_SPACE> 





This tag must be used within the context of a <FIGURE> tag. 





None. 


DESCRIPTION This tag is used in the context of a formal figure. Use <FIGURE_ATTRIBUTES> 


to adjust the pagination and placement of the figure. 


A formal figure is sometimes long. If you think one of your figures will be 
longer than a page, use the MULTIPAGE argument. Your figure will then 
be placed on the current page and continued on following pages, as space 
permits. 


A multipage figure can contain one or more elements (that is, one or more 
<FIGURE_FILE> , <FIGURE_SPACE> , and <CODE_EXAMPLE> tags.) 


If your multipage figure (consisting of a single <CODE_EXAMPLE> ) contains 
no blank lines, you might want to insert <VALID_BREAK> tags in the figure. 
The <VALID_BREAK> tags specify reasonable page breaking points. See the 
description of the <VALID_BREAK> tag for more information. 


A one-page (or smaller) figure’s position in the output file can change. If the 
figure does not completely fit on the current page, the entire figure is placed 
at the top of the next page. The text that follows the example in the SDML 
file then is used to fill the current output page. When the figure’s position can 
change, the figure is said to float. 


Floating is the default condition for a figure that has a caption and fits on 
one page. If you want the placement of a figure without a caption to float, 
you must specify the FLOAT argument if your figure fits on one page. A 
multipage figure never floats. 


The argument KEEP will override the default FLOAT condition for a figure 
with a caption. . 





EXAMPLE .- 
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See the first example in the <FIGURE> tag. 


<FIGURE_FILE> 


<FIGURE_FILE> 


Includes a graphics file in your output file if the output device has graphics 
capability. 








FORMAT <FIGURE_FILE> (target-device 
\ file_spec 
\ SPACE 
\ vertical-size 
[ \ position]) 
ARGUMENTS _ target-device 


Specifies a keyword indicating the output device on which the graphics file 
will be printed. Only an LNO3 laser printer or an LPS40 laser printer (a 
PostScript device) support graphics capabilities. However, a third keyword is 
recognized, a line printer. Each keyword allows you to insert the necessary 
amount of white space for the specific output device. 


Keyword _ Device Output 
LNO3 LNO3 Laser Specified graphics file is output 
_ Printer 
POSTSCRIPT LPS40 Laser Specified postscript file is output 
Printer 
LINE_PRINTER Line Printer If specified, the file-spec argument is 


ignored, and blank space is output. 


If you specify <FIGURE_FILE> for a given device and subsequently process 
the file on another output device, no output will appear in the position of the 
<FIGURE_FILE> tag. 


file-spec. | 
Specifies the graphics file. 


SPACE 


Lets you reserve blank space in the output file for the device for which no 
graphic file exists. Use SPACE when you expect to process a file for more 
than one output device, but do not have graphics files for all devices. 


vertical-size 

Specifies the vertical size of the printed graphic. It must be a numeric 
argument, specifying the depth in units of picas (1 pica = 1/6 inch). 
position 

Specifies an optional keyword that determines how the graphic aligns in 
relationship to the text: 


e null — aligns with the normal left text margin. 


9-81 


<FIGURE_FILE> 


related tags 


restrictions 


required 
terminator 


e WIDE — aligns at the leftmost position of the image area (if your format 
has a wide left gutter). 





e <ICON> 


® <FIGURE> 





You must use an LNO3 or PostScript laser printer to print graphics files. 
You must use <FIGURE_FILE> in the context of the <FIGURE> tags. 


If you use the <FIGURE_FILE> tag in a file that you process for multiple 
output devices, you must supply a tag for each device, using the SPACE 
keyword for devices for which you do not have graphics. 





None. 


DESCRIPTION The <HIGURE_FILE> tag enables you to automatically include graphics files 
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for printing along with your text in the output file. 


To ensure that your figure is the right size for inclusion with your output, 
follow this procedure: 


1 Create and print your graphics file full size (100 percent). 
2 Measure it. 


3 If the figure at 100 percent is the desired size and will fit on the page, 
incorporate that measurement into the <FIGURE_FILE> tag. Otherwise, 
calculate a percentage reduction and use the graphics editor to reduce 
the figure to the desired size. Print and measure the graphics file and 
incorporate the measurement in the <FIGURE_FILE> tag. 


b 


Process the SDML file and print the output. 


ol 


Evaluate the result. If it is satisfactory, you are finished. Otherwise, 
change either of the following. 


e One or both keywords specified in <FIGURE_FILE> to correct the 
alignment, and/or the spacing for the figure 


e The graphics file itself to correct the size, content, or both 


Because there is an interaction between changing the contents or size of 
the graphics file and specifying its placement in the <FIGURE_FILE> tag, 
satisfactory results may require several loops through the process, much like 
coding complicated tables. Refer to Chapter 3 for information on coding 
tables. 


-<FIGURE_FILE> 





EXAMPLES 


<FIGURE>(The Front View) 
<FIGURE_FILE>(LNO3\frontpanel .six\6) 


<ENDF IGURE> 

This example shows how a numbered figure is coded. 
<FIGURE> 
<F IGURE_FILE>(LNO3\example1 .six\10) 
<ENDF IGURE> 

This example shows how an unnumbered figure is coded. 
<FIGURE> 


<FIGURE_FILE>(LNO3\SANTA.SIX\15) 
<FIGURE_FILE>(LINE_PRINTER\Illus. of Santa Claus\10) 
<ENDF IGURE> 


This example illustrates a file that can be printed on any one of three output 
devices. If this file is processed for an LNO1 laser printer or the line printer, 
the sixel file will not be included, but blank space will be left. If this file is 
processed for an LNO3 laser printer, the sixel file will be output as follows: 





<Figure>(The VAX DOCUMENT Lifecycle\cycle_fig) 
<Figure_file>(LNO3\cycle.six\22) 
<Figure_file>(Line_printer\cycle_fig\20) 
<Figure_file>(POSTSCRIPT\SPACE\22) 

<Endfigure> 


When this example is processed for LNO3 output, the graphics figure 
“cycle.six” is included. When it is processed for other output devices, blank 
space is output. 


9-83 


ae 


<FIGURE_SPACE> 


<FIGURE_SPACE> 


Marks the space required for a figure that will be pasted in during final 
production. 





FORMAT 


<FIGURE_SPACE> ({ ae are [\ text) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


pyre SPACE Doping, . AAT ys, 


KE ND#i ewkE> 
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value 

Specifies the amount of vertical space to be left on the page. The value should 
be specified in picas, a scale used by typesetters. There are approximately 6 
picas to the inch. Thus, if the figure to be pasted in is 4 inches high, you 
should specify 24. If you do not specify a value, a default value of 2 is used. 


FULL_PAGE 


Specifies that a full blank page is reserved for the figure. 


text 
Specifies text that describes the status of the figure, an art file number or the 
words “To Be Set”. The text is output in the middle of the space left for the 
figure. 





° <FIGURE> 

® <FIGURE_ATTRIBUTES > 
° <FIGURE_FILE> 

: <REFERENCE > 

° <FIGURE_SPACE> 


. <LINE_ART> 





Must be used in the context of a <FIGURE> tag. 


The value of the <FIGURE_SPACE> tag must not exceed page depth 
limitations. 





None. 


I a pedline 


<FIGURE_SPACE> 





DESCRIPTION The <FIGURE_SPACE> tag causes a blank space to be left on the page for a 
figure that will be pasted in by hand during final production. 


If you specify some descriptive text in the second argument, that text is output 
in the middle of the space left for the figure. 





EXAMPLE See the example in the discussion of the <FIGURE> tag. 
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<FINAL_CLEANUP> 


<FINAL_CLEANUP> 


Provides explicit formatting instructions for the text formatter to be used 
for final formatting and cleanup. 








FORMAT COLUMN_BREAK 
<FINAL_CLEANUP> ( } L/NE_BREAK 
‘ UPO() SAGE BREAK 
SPECIAL _BREAK 
ARGUMENTS COLUMN_BREAK 


related tags 


restrictions 


required 
terminator 
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Specifies that a new column of text is to be started at the place where the 
<FINAL_CLEANUP> tag occurs. This argument is only valid in a two-column 
design (ARTICLE or REPORT.TWOCOL) and should be used only to make 
the final documentation look better. 


LINE_BREAK 


Specifies that the text formatter is to place the remaining text in the paragraph 
onto a new line of output. 


PAGE_BREAK 


Specifies that the text formatter should place following text on a new page of 
output. 


SPECIAL_BREAK 


Specifies a special break when vertical spacing appears to be lost. In some 
circumstances, the output of a two-column page may have had some of 

its vertical spacing lost due to the text formatter processing, for example, 

a heading tag may not have any space before it. The SPECIAL_BREAK 
argument should be used only if there is a spacing problem and only after 
you are ready to give your document a final format check, because changes to 
the source file may help the text formatter resolve the spacing problem. 





¢ = <COLUMN> — ARTICLE and REPORT.TWOCOL 
¢ = <LINE> 


e <PAGE> 








<FINAL_CLEANUP> 





DESCRIPTION The <FINAL_CLEANUP> tag is not a generic markup tag; it explicitly instructs 
the text formatter to change aspects of a page makeup. 


In a single-column doctype, the <FINAL_CLEANUP> tag enables you to 
specify line breaks and page breaks using the LINE_BREAK and PAGE_ 
BREAK keyword arguments. In a two-column doctype, you can use the 
COLUMN _BREAK keyword argument to start a new column of text. The 
SPECIAL_BREAK keyword argument is used only rarely at the final stage of 
production to place “finishing touches” into your document. 


When you are working with the ARTICLE or REPORT.TWOCOL doctypes, 
you may need to make some final adjustments when your text is complete. 
The text formatter makes formatting decisions based on your source file. It 
is more difficult for the text formatter to create a well-formatted two-column 
page than it is a well-formatted one-column page. Therefore, the output of 
these doctypes may need additional “finishing touches” during the last stage 
of document production. 


<FOOTNOTE> 


<FOOTNOTE> 


Places a footnote character in text, using the character specified in the 
tag's argument, and places the footnote text at the bottom of the page. 





FORMAT 


<FOOTNOTE> (char \ footnote-text) 





ARGUMENTS 


char 

Specifies the footnote character. The character can be a single character, 
a number, or one of the following keywords denoting special characters 
associated with footnote references: 


DAG (t) 
DDAG (t) 
R (®) 

S (§) 
™ (_) 


When placing a footnote in a table, you must use a number or one of the 


keywords as the footnote character. 


related tags 


restrictions 
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If you use more than one of the keywords allowed for table footnotes, you 
should declare them in the following order to ensure that the footnotes print 
in the correct order at the bottom of the page: 


1 T™ 

2 R 

3 5S 

4 DAG 
5 DDAG 


footnote-text 
Specifies the text of the footnote. 





® <FOOTREF> 
bd <FOOTNOTE_TEXT> 





Invalid in math. 
The following restrictions apply to footnotes within tables: 


¢ There can be no more than twelve footnotes in a table. If you use a 
nonnumeric footnote character, there can be no more than seven numeric 
footnotes. 


<FOOTNOTE> 


e All table footnotes must be declared at the top of the table using a 
<FOOTNOTE> tag just after the <TABLE_SETUP> tag. <FOOTNOTE> tags 
must not be specified in a nested table. 


¢ Callouts within the body of a table must be labeled with a <FOOTREF> 
tag. It is the <FOOTREF> tag that causes the footnote character to appear. 


e Footnotes in the body of a multipage table appear at the bottom of a page 
only if they are called out on that page. 


e Footnotes called out in the heading of a multipage table appear at the 
bottom of each page of the table. 


e Footnotes on a title page and copyright page should be specified using 
the <FOOTNOTE_TEXT> tag. 





required None. 
terminator 





DESCRIPTION The <FOOTNOTE> tag causes a footnote character to appear in text at the 


place where the tag is located. The text of the footnote is specified as the 
second argument to the tag, and appears at the bottom of the page. 





EXAMPLES 


ND 


<P>The <TAG>(footnote) tag may produce output that looks like 
this .<FOOTNOTE>(1\Note how 
footnote text appears at the bottom of the page.) 


This example may produce the following output: 


The <FOOTNOTE> tag may produce output that looks like this.! 


<TABLE>(Rules for Determining Expression Modes\express_modes_tab) 


<TABLE_ATTRIBUTES> (MULTIPAGE) 

<TABLE_SETUP> (2\43) 

<FOOTNOTE>(1\A footnote in a table.) 
<TABLE_HEADS>(Expression\Value Type) 
<TABLE_ROW>(Integer value\Integer) 
<TABLE_ROW>(String value\String<FOOTREF>(1)) 
<TABLE_ROW>(Integer lexical function\Integer) 
<TABLE_ROW>(String lexical function\String) 
<TABLE_ROW>(Integer symbol\Integer) 
<TABLE_ROW>(String symbol\String) 
<TABLE_ROW>(Any value .AND. or .OR. any value\Integer) 
<TABLE_ROW>(Any value\Integer) 
<TABLE_ROW>(Any value\Integer) 

<ENDTABLE> 


This example shows how to produce a two-column table that contains a 
footnote. A <FOOTNOTE> tag is placed directly after the <TABLE_SETUP> 
tag to declare the existence of a footnote and to identify the footnote text. 
A <FOOTREF> tag then is placed in the exact location of the footnote 
superscripted reference mark in the table. 


Make sure to place the <FOOTREF> tag within the argument to a <TABLE_ 


ROW> tag. 


1 Note how footnote text appears at the bottom of the page. 


<FOOTNOTE> 
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The example may produce the following output: 


Table x—x Rules for Determining Expression Modes 


Expression Value Type 
Integer value Integer 
String value String’ 
Integer lexical function Integer 
String lexical function String 
Integer symbol Integer 
String symbol String 

Any value .AND. or .OR. any value Integer 

Any value Integer 

Any value Integer 


1A footnote in a table. 


<FOOTNOTE_TEXT> 


<FOOTNOTE_TEXT> 


Specifies the text of a footnote in the context of a heading, title page, or 
copyright page. 





FORMAT 


<FOOTNOTE_TEXT > (char \ text) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


char 

Specifies the footnote character. The character can be a single character 
or number, or it can be one of the following keywords denoting special 
characters associated with footnote references: 


DAG (t) 
DDAG (t) 
R (®) 

S (§) 
™T™ (_) 


text 
Specifies the text associated with the footnote. 





. <FOOTREF> 


. <FOOTNOTE> 





Required when footnotes are specified in the context of header-level text 
and title pages/copyright pages. Must not be used for table footnotes. The 
<FOOTNOTE_TEXT> tag must follow the related <FOOTREF> tag in the 
source file. 





None. 





DESCRIPTION The tag 9<FOOTNOTE_TEXT> allows you to specify the text placement of a 


footnote in the following special circumstances: 


e¢ When you want to specify a footnote in an argument to a header-level 
tag (<HEAD1>, <HEAD2>, etc.) 


e When you want to specify footnote text related to a footnote character on 
the title page of a document. 


In all other cases, you should use the <FOOTNOTE> tag. 
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<FOOTNOTE_TEXT> 





EXAMPLES 


<HEAD1>(Introduction to The News Today<footref> (TM) ) 
<footnote_text>(TM\The News Today 

is a trademark of the American Television 

Society.) 


This example illustrates the use and placement of the <FOOTNOTE_TEXT> tag 
and its related <FOOTREF> . | 


<front_matter> 

<TITLE_PAGE> 

<product> (CATCHUP<footref> (TM) ) 

<title>(Guide to Growing Premium Fruit Bearing Plants) 
<ABSTRACT>(June 1986) 

This document describes how to cultivate smooth-skinned 
tomato plants. 

<ENDABSTRACT> 


<footnote_text>(TM\CATCHUP is a trademark of Tomato Magnates, Inc.) 
<ENDTITLE_PAGE> 


This example illustrates the placement of a footnote on the title page of a 
document. The exact placement of the footnote, in the final output, is based 
on the document-specific design specified by the book designer. 
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<FOOTREF> 


<FOOTREF> 


Creates one or more footnote characters in text or in a table using the 
footnote numbers or characters as arguments. 





FORMAT 


<FOOTREF> (char-17 [\ char-2 ... \ char-9]) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


char-1...9 


The character(s) for the footnote. A character can be a single character or 
number, or it can be one of the following special characters associated with 
footnote references: 


DAG (t) 
DDAG (t) 
R (®) 

S (§ 

T™ (°) 


In a table, the reference must be to a number or to one of the special 
characters. 





be <FOOTNOTE> 


° <FOOTNOTE_TEXT> 





Invalid in math. 





None. 


DESCRIPTION 


The <FOOTREF> tag causes as many as nine superscripted characters to 
appear in the text at the place where the tag is located in the SDML file. 


There are two occasions that require use of the <FOOTREF> tag: 
e Where the same footnote in text needs to be called out more than once 


e Wherever a footnote is called out in a table 


If you have a footnote in the text to which you want to refer more than 
once, you should use a <FOOTNOTE> tag to label the first occurrence of the 
footnote and the <FOOTREF> tag to label the subsequent characters to that 
note. 


The text formatter does not automatically repeat text footnotes if references 
are output on more than one page. 
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<FOOTREF> 


If you have one or more footnotes within a table, you must declare the 
footnotes using the <FOOTNOTE> tag just after the <TABLE_SETUP> tag. 
You can then use the <FOOTREF> tag to label the characters within the table 
body. Within a table, the presence of the <FOOTREF> tag causes the text of 
the footnote to appear at the bottom of the table, rather than at the bottom of 
the page. If the table is longer than a single page, and if the <FOOTREF> tag 
appears multiple times, the footnote text appears at the bottom of the table 
on each page containing the reference. 


Make sure to place the <FOOTREF> tag within the argument to a 
<TABLE_ROW> tag. 





EXAMPLE 


<P>The macro format for a $GETDVI request is:<FOOTNOTE>(1\The 

eighth (last) 

argument is not used; it is reserved for future use.) 

<CODE_EXAMPLE> 

$GETDVI [{efn], [chan] , [devnam] ,itmlst, [iosb] , [astadr] , lastprm] 
<ENDCODE_EXAMPLE> 
<P>The high-level language format for a $GETDVI request is:<FOOTREF>(1) 
<CODE_EXAMPLE> 

SYS$GETDVI([efn] , [chan] , [devnam] ,itmlst, [iosb] , [astadr] , [astprm] ) 
<ENDCODE_EXAMPLE> 


This example may produce the following output: 
The macro format for a $GETDVI request is:! 
$GETDVI [efn],[chan],[devnam],itmlst,[iosb],[astadr],[astprm] 
The high-level language format for a $GETDVI request is:1 
SYS$GETDVK([efn],[chan],[devnam],itmst, [iosb],[astadr],[astprm]) 


! The eighth (last) argument is not used; it is reserved for future use. 
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<FORMAT> 


<FORMAT> 


Enables <FCMD>, <FPARMS>, and <FPARM> to distinguish formatted 
command keywords and parameters. 





FORMAT <FORMAT> I Heading-text | 
WIDE 





ARGUMENTS _heading-text 
Specifies a heading. 


WIDE 


Indicates, for document styles in which the left margin is indented, that the 
body of the formatted text should be extended into the margin. 





related tags °  <FCMD> 
s <FPARM> 


° <FPARMS> 








restrictions Invalid in math, monospaced examples, tables, and figures. 
required <ENDFORMAT> 
terminator 





EXAMPLE See the examples in the discussion of the <FCMD> tag. 


<FPARM> 


<FPARM> 


Specifies a parameter to be formatted following <FPARMS> , aligned under 
the parameter list portion of a keyword/parameter list pair. 





FORMAT | <FPARM> (parameter-list) 





ARGUMENTS = parameter-list 


Lists additional command parameters, if any. 





related tags ° = <FCMD> 
e = <FORMAT> 


® <FPARMS> 











restrictions Enabled only within <FORMAT> . 

required None. 

terminator 

EXAMPLE See the examples in the discussion of the <FCMD> tag. 


<FPARMS> 


<FPARMS> 


Specifies the parameter portion of a formatted command/parameter pair 
in a format section. 





FORMAT 


<FPARMS> (parameter-list) 





ARGUMENTS 


related tags 


parameter-list 
Lists the command parameters, if any. If there are no parameters, you can 
specify the argument as null: <FPARMS>. 





* <FCMD> 
. <FORMAT> 


e <FPARM> 











restrictions Enabled only within <FORMAT> . 

required None. 

terminator 

EXAMPLE See the examples in the discussion of the <FCMD> tag. 
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<FRONT_MATTER> 


<FRONT_MATTER> 


Begins the front matter of a book. 





FORMAT 


<FRONT_MATTER> [(symbol-name)] 





ARGUMENTS 


related tags 


symbol-name 
Specifies the term that you assign to the front matter. A symbol-name 
argument is required if the front_matter is to be part of a bookbuild. 


Symbol-names must not exceed 31 characters, and must only contain 
alphabetic letters, numbers, or underscores. Do not begin a er name 
with an underscore. 


\ 





e See the list of tags in the description. 











restrictions None. 

required <ENDFRONT_MATTER> 

terminator 

DESCRIPTION The <FRONT_MATTER> tag enables the tags that create the front_matter of a 


book. The following tags are used to create the front matter: 


<ABSTRACT> 


<CONTENTS_FILE> 


<COPYRIGHT_DATE> 


<COPYRIGHT_PAGE> 


<FRONT_MATTER> 


<ORDER—NUMBER> 


<PREFACE> 


<PREFACE_SECTION > 


<PRINT_DATE> 


<REVISION—INFO> 


<TITLE> 


<TITLE_PAGE> 


Each of these tags is listed alphabetically within this chapter. The order in 
which these tags are used is shown in the following example. 


<FRONT_MATTER> 





EXAMPLE 


<FRONT_MATTER> (front) 

<TITLE_PAGE> 

<TITLE>(My Latest Book) 

<ORDER_NUMBER> (xx- 12345) 

<ABSTRACT> 

This book describes the latest changes to any product. 
<ENDABSTRACT> 
<REVISION_INFO>(Revision/Update Information:\This is a new manual.) 
<ENDTITLE_PAGE> 

<COPYRIGHT_PAGE> 

<PRINT_DATE>(March 1987) 

<COPYRIGHT_DATE> (1987) 

<ENDCOPYRIGHT_PAGE> 

<PREFACE> (11) 

<PREFACE_SECTION>(The changes to your system) 
<ENDPREFACE> 

<ENDFRONT_MATTER> 


This example shows the order of all the front_matter tags, and how they 
could be used in a file that contains the front_matter of a book. 
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<GDEF> 


<GDEF> 


Begins the text that defines a term in a glossary. 





FORMAT 


<GDEF> (definition) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


definition 
Specifies the definition of the term. 





e® <GLOSSARY> 
e <GTERM> 


° <GREF> 





Can only be used between <GLOSSARY> and <ENDGLOSSARY> tags. 





None. 





DESCRIPTION See the description of the <GLOSSARY> tag. 





EXAMPLE 
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See the example in the discussion of the <GLOSSARY> tag. 


<GLOSSARY> 


<GLOSSARY > 


Formats a glossary of terms in a document or book. 





FORMAT <GLOSSARY > (text/ \ symbol-name]) 





ARGUMENTS _ text 


Specifies any text string that you want to label the start of the glossary. If no 
text is specified, the default text is the term “Glossary.” 


symbol-name 
Specifies the term that you assign to the glossary and then use to reference it. 


All symbol-names must not exceed 31 characters, and must only contain 
alphabetic letters, numbers, or underscores. Do not begin a symbol-name 
with an underscore. 








related tags © = <GTERM> 
. <GDEF> 
restrictions The symbol-name argument is required if this file will be included as part of 


a bookbuild. 


required <ENDGLOSSARY> 
terminator 





DESCRIPTION To create a glossary of terms, use the <GLOSSARY> tag to establish the 
beginning format. Follow this with a list of <GTERM> tags, with the glossary 
words defined as arguments to the <GTERM> tags. Typically, a definition 
of each glossary term follows the term itself. Create each definition with a 

<GDEF> (definition) tag. 





EXAMPLE 


<Glossary> 

<gterm> (habitat) 

<gdef>(An area or natural environment. ) 
<gterm> (habitual) 

<gdef>(Acting according to habit.) 
<gterm> (hack) 

<gdef>(A worn-out horse.) 

<gterm> (hackneyed) 

<gdef>(Trite, banal.) 

<endglossary> 
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<GLOSSARY > 


This example produces the following output: 


Glossary 
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habitat: An area or natural environment. 
habitual: Acting according to habit. 
hack: A worn-out horse. 


hackneyed: Trite, banal. 


<GREF> 


<GREF> 


Marks a cross-reference to a term within a glossary. 





FORMAT ~ <GREF> (term) 





ARGUMENTS term 


Specifies the term referred to. 





related tags e  <GLOSSARY> 
e = <GTERM> 


<GDEF> 


The following tags label other types of cross-references: 


<REFERENCE> 
<CALLOUT_REF> 








restrictions Invalid in math. 
required None. 
terminator 





DESCRIPTION The <GREF> tag marks a cross-reference to a term within a glossary. 


<GTERM> 


<GTERM> 


Labels a term to be defined in a glossary. 





FORMAT <GTERM> (term) 





ARGUMENTS term 


Specifies the term to be defined in the glossary. 











related tags °  <GLOSSARY> 
¢ = <GDEF> 
°¢ = <GREF> 
restrictions Can only be used between <GLOSSARY> and <ENDGLOSSARY> tags. 
required <GDEF> 
terminator 





DESCRIPTION The <GTERM> tag labels a term to be defined in a glossary. 





EXAMPLE See the example in the tag <GLOSSARY> . 
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<HEADx> 


<HEADx> 


Marks a heading of the level specified (1 through 6). 





FORMAT 


<HEADx> (heading-text | \ symbol-name)]) 





ARGUMENTS 


related tags 





restrictions 


required 
terminator 


heading-text 

Specifies the text of the heading. If the book design you are using produces 
headings that are all capital letters in your output, those letters will appear 
that way regardless of how you enter them in your input file. You should, 
however, use uppercase and lowercases letters according to your local 
conventions in order to obtain the proper capitalization of the heading in 
the table of contents and in cross-references. 


symbol-name 

The name of the symbol to be used in all references to this heading and 
the text following. Symbol-names must not exceed 31 characters, and must 
only contain alphabetic letters, numbers, or underscores. Do not begin a 
symbol-name with an underscore. 





sd <SUBHEAD1> 
be <SUBHEAD2> 


© = <CHEAD> ¢éauet hd 





None. 





None. 





DESCRIPTION Each of the six tags, <HEADI>, <HEAD2>, <HEAD3>, <HEAD4>, 


<HEAD5>, and <HEAD6> does the following: 

e Outputs the heading text passed to it in its first argument 
e Automatically numbers the heading 

e Resets all of the counters for lower heading levels (if any) 


e Specifies the symbol-name with which cross-references to that heading 
should be made 


Entries for each of the headings may appear in the table of contents, 
depending on the doctype design. 


<HEADx> 


The proper choice of the heading level depends on an understanding of the 
logical structure of the document you are writing. A <HEAD2> tag will 
always be logically subordinate to a <HEAD1> tag. The same is true for the 
relationship between <HEAD3> and <HEAD2>; <HEAD4> and <HEAD3> ; 
and so on. 





EXAMPLES 


1] <HEAD1>(Running Tasks\tasks) 


This tag labels a first-level heading. 


2 <HEAD2>(SET and SHOW Commands\set_show_sec) 
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This tag labels a second-level heading. 


You could reference this heading anywhere in the document by using the 
tag <REFERENCE> (set_show-_-sec). In this example, if the heading was the 
second sublevel of the first section in the document, the reference would be 
output as Section 1.2. 


If you wanted to control the output of the reference, you could reference it in 
any of the ways listed in the following table: 


Reference Output 

<REFERENCE> (set_show) Section 1.2 
<REFERENCE> (set_show\value) 1.2 

<REFERENCE> (set_show\text) Set and Show Commands 


<REFERENCE> (set_show\full) Section 1.2, Set and Show Commands 


<HELLIPSIS> 


<HELLIPSIS> 


Places horizontal ellipsis points on a line. 














FORMAT <HELLIPSIS> 
related tags °  <ELLIPSIS> 
restrictions Invalid in math. 
required None. 

terminator 





DESCRIPTION The <HELLIPsis> tag places horizontal ellipsis points on a line. Often, it is 
used to label omitted material. 





EXAMPLE 


<P>A horizontal ellipsis may provide an indefinite ending <HELLIPSIS> 


This example may produce the following output: 


A horizontal ellipsis may provide an indefinite ending ... 


<HYPHENATE> 


<HYPHENATE> 


Provides information about legal hyphenation of a word of text. 





FORMAT 


<HYPHENATE> (part? \ part2[\ ... part9)) 





ARGUMENTS 


related tags 


restrictions 


part1 ... part9 

Specifies the word of text and its valid hyphenation points. Each argument 
to the tag specifies a portion of the word. Use the argument delimiter, the 
backslash, to indicate the hyphenation points. 





° <FINAL_CLEANUP> —LINE_BREAK 
e <LINE> 


° <KEEP> 





This tag is invalid in math and in monospaced examples. 


DESCRIPTION 


Use this tag when you are not satisfied with line breaks within paragraphs in 
your final output and you determine that the line breaks are caused because 
a word is not being hyphenated. This tag is also useful when a word or term 
(usually a technical term that is not commonly used) is not being hyphenated 
correctly. 


This tag does not force a term to be hyphenated; it merely provides the text 
formatter with information about legal places to break this occurrence of the 
word, should you need to break the word. 





EXAMPLE 


<p>Among the more common literary devices used by poets are 
<hyphenate>(on\o\mat\o\poe\ia) and anthropomorphism. 
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The following shows the output this example may produce: 


Among the more common literary devices used by poets are onomato- 
poeia and anthropomorphism. 


<ICON>. 





<ICON> 


Allows you to include a graphic image in your printed output and print text 
parallel to the image. The text is printed either to the right or left of the 
picture. 





FORMAT <ICON> 





ARGUMENTS = None. 





related tags e = <FIGURE_FILE> 
e = <ICON_FILE> 


7 <ICON_—TEXT> 





restrictions Use the <ICON> tag for graphics that have a depth and width of 
- approximately 2 inches. Use the <FIGURE_FILE> tag for larger graphics. 


The output device must be able to support graphics. 





required <ENDICON> 
terminator 





DESCRIPTION Use the <ICON> tag when you want to print a small graphic with 
explanatory text printed next to it. 





EXAMPLES 


<ICON> 

<ICON_FILE>(LNO3\small_art .six\1.5\2.0\RIGHT) 
<ICON_TEXT>(The text accompanying the 

small piece of art. The text can be smaller or larger 
than the graphic; the <tag>(ICON) tags make the necessary 
adjustments for the output.) 

<ENDICON> 


This example shows how to code a graphic on the right, with text on the left. 
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<ICON> 


PF) = <ICON> 
<ICON_FILE>(LNO3\SANTA.SIX\15\11) 
<ICON_FILE>(LINE_PRINTER\Santa\3\8) 
<ICON_TEXT>(The image at the left is of an American icon. 
The personification of the spirit of Christmas, 
usually represented as a jolly, fat old man with 
a white beard and a red suit is also called 
<quote>(Saint Nicholas) or <quote>(Saint Nick.)) 
<ENDICON> 
<ICON> 
-<ICON_FILE>(LNO3\ELLIPSE.S1X\15\10\RIGHT) 
<ICON_FILE>(LINE_PRINTER\ellipse\3\8\RIGHT) 
<ICON_TEXT>(The image at the right is of an ellipse: 
a conic section taken neither parallel to an element nor parallel 
to the axis of the intersected cone. 
<ENDICON> 


This example shows one graphic placed on the left, with text on the right, 
followed by a second graphic placed on the right, with text on the left. The 
output appears as follows: 


The image at the left is of an American icon. 
The personification of the spirit of Christmas, 
usually represented as a jolly, fat old man with 
a white beard and a red suit is also called “Saint 
Nicholas” or “Saint Nick.” 





The image at the right is of an ellipse: a conic 
section taken neither parallel to an element nor 
parallel to the axis of the intersected cone. 
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<ICON_FILE> 


<ICON_FILE> 


Specifies a graphics file that accompanies text within the <ICON> and 
<ENDICON> tags. 








FORMAT <ICON_FILE> (target-device 
\ file-spec 
\ depth 
\ width 
[\ RIGHT]) 
ARGUMENTS _ target-device 


related tags 


restrictions 


Specifies a keyword indicating the output device on which the graphics file 
can be printed. 


Keyword Device Output 

LNO3 LNO3 Laser Printer | Specified graphics file is output 

POSTSCRIPT POSTSCRIPT Laser Specified POSTSCRIPT file is output 
Printer 

LINE_PRINTER Line Printer If specified, the file-spec argument is 


ignored, and blank space is output. 


file-spec 

Specifies the graphics file. No default file type is supplied. 

depth 

Specifies the depth of the graphic. This argument must be a number 2 

representing the depth in picas (1 pica = 1/6 inch). a 
PA 

width /. 

The width of the graphic, also indicated in picas. 

RIGHT \ 


Indicates that the graphic image is to be placed to the right of the text. If 
you do not specify this argument, the image is placed on the left of the text 
specified in the <ICON_TEXT> tag. 





° <FIGURE_FILE> 
® <ICON> 


° <ICON_— TEXT> 





You must have an output device that can print graphics files. 


Only valid when used between the <ICON> and <ENDICON> tags. 
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<ICON_FILE> 





required None. 
terminator 





DESCRIPTION Specifies a graphics file that accompanies text within the <ICON> and 
<ENDICON> tags. The specified file should be a graphics file suitable for 
printing on the specified output device. 





EXAMPLES See the examples in the <ICON> tag description. 
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<ICON_TEXT> 


<ICON_TEXT> 


Labels the text that accompanies a graphic image included in text with the 
<ICON> and <END_ICON> tags. 





FORMAT 


<ICON_TEXT> (text) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


text 
Specifies the text that accompanies the graphic. It can be as SiGng as you wish 
and can include paragraphs and lists. 





bd <ICON> 


e <ICON_FILE> 





Must be used within the context of the <ICON> tag. 





None. 





DESCRIPTION The <ICON_TEXT> tag labels the text that accompanies a graphic image 


included in text with the <ICON> and <END_ICON> tags. 





EXAMPLE 


See the <ICON> tag description. 
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<INCLUDE> 


<INCLUDE> 


Causes the contents of a specified file to be included in the current input 
file for processing. 





FORMAT <INCLUDE> (file-spec) 





ARGUMENTS _file-spec 
Specifies the file to be included. 


If a logical name is specified, instead, and the source file is an element of a 
book, you can define the logical name using an <INCLUDES_FILE> tag in the 
book’s profile. If the source file is not an element of a book, or if the profile 
does not contain the <INCLUDES_FILE> tag, be sure to define the logical 
name before processing the file through VAX DOCUMENT. 





related tags @ = <EXAMPLE_FILE> 
°  <TABLE_FILE> 





restrictions The <INCLUDE> tag is invalid in an argument to a tag. 


In a file that contains a book element to be processed through a bookbuild, 
make sure to place the book element tag (for example, <CHAPTER> ) as the 
first tag in the file. The <INCLUDE> tag should never be placed before the 
book element tag. 





required None. 
terminator 





DESCRIPTION The <INCLUDE> tag causes the contents of a specified file to be included in 
the current input file for processing. 





EXAMPLE 


<INCLUDE> (doc_local_templates : boilerplate .sdm1) 
This example shows the inclusion of a file that does the following: 
e Contains text that might be repeated multiple times in a source file 


e Js used in more than one document 


If the file specification doc_local_templates:boilerplate.sdml was not used, but 
instead substituted with a logical-name, the logical-name could be equated to 
the file specification by using the <INCLUDES_FILE> tag in the profile. 


<INCLUDES_FILE> 


<INCLUDES_FILE> 


Equates a logical name with a file specification during processing of a 
profile. 





FORMAT 


<INCLUDES_FILE> (logical-name \ file-spec) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


logical-name 
Specifies the logical name for the included file. You can use this name as the 
argument to an <INCLUDE> tag. 


file-spec 
Specifies the file specification into which the logical name translates. 





° <PROFILE> 
be <ELEMENT> 


° <INCLUDE> 





Must be used in the context of a profile. 





None. 


DESCRIPTION You can place the <INCLUDES_FILE> tag in your profile to define a logical 


name for a file whose contents are included in one of your element files. 
The first argument to <INCLUDES_FILE> is the logical name for the included 
file. You use this name as the argument to the <INCLUDE> tag. The second 
argument specifies the actual file specification into which the logical name 
translates. 


<INCLUDES_FILE> tags follow the <ELEMENT> tag for which they are 
needed. During a bookbuild, VAX DOCUMENT establishes the logical 
name definition for each <INCLUDES_FILE> tag before it actually reads and 
processes the book element file names in the preceding <ELEMENT> tag. The 
logical name remains defined during the processing of later book elements. 


When an book element is processed by itself (when you use the /PROFILE 
qualifier on the command line), VAX DOCUMENT again establishes the 
logical-name definitions that were specified by the <INCLUDES_FILE> tags in 
the profile. 
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<INCLUDES_FILE> 





EXAMPLE 


<ELEMENT> (error_chap.SDML) 
<INCLUDES_FILE>(Error_msg_tab\Mydisk: [Mydirectory]my_very_long_table.sdm1l) 


This example illustrates how the <INCLUDES_FILE> tag is used to define a 
logical name for a file (called “my_very_long_—table.sdml”) which is being 
kept in the directory [Mydirectory]. In the book element file ERROR— 
CHAP.SDML, the writer includes the table of error message codes with 
the tag: 


<include>(error_msg_tab) . 
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<INDEX_FILE> 





<INDEX_FILE> 


Specifies the position in a book (or document) where an index file should 
be included in the output. 





FORMAT <INDEX_FILE> /(file-spec)] 





ARGUMENTS _file-spec 
If you place the <INDEX_FILE> tag in an SDML file that will be included 


in another file later, you must specify the exact file-spec of the index as the 
<INDEX_FILE> tag’s argument. 











related tags *  <PROFILE> 
restrictions None. 
required None. 
terminator 





DESCRIPTION The <INDEX_FILE> tag specifies the position in a source file where an index 
output file should be included. This tag does not produce an index, but 
simply indicates placement of the index file. An index file is produced when 
the qualifier ”/INDEX” is specified on the DOCUMENT command line. 


The profile tags <INDEX_FILE> and <CONTENTS_FILE> can be placed in 
either the profile of a book or in a source file. If you are creating a book (with 
a profile to be processed through a bookbuild), place these tags in the profile 
to be sure of correct: placement in the output. 


An index file always receives the filetype .DVI —device, where device is 
the type of output device you specified on the command line. For more 
information on index generation, see Chapter 7. 


To create an index from an individual file that contains an <INDEX_FILE> 
tag, specify the ”/INDEX” qualifier on the command line. 





EXAMPLE To see the result of the <INDEX_FILE> tag, refer to the index in this manual. 
The <INDEX_FILE> tag was placed in the profile file after the last appendix 
file. 


<INTERACTIVE> 


<INTERACTIVE> 


Begins an example dialog between user and system and enables the tags 
<S> and <U> to distinguish system text from user text. 








FORMAT <INTERACTIVE> (code) 
or 
[KEEP \ ] 
<INTERACTIVE> /[( [WIDE\\ MAXIMUM] )] 
interactive code or text 
<ENDINTERACTIVE> 
ARGUMENTS'- code 


9-118 


Specifies a code fragment you want to insert into your text. 


If this argument is not specified, the terminator <ENDINTERACTIVE> is 
required. 


KEEP 


Specifies that the example is not to be broken across pages, that is, if the 
example does not fit on the current page, it will be placed on the next page. 
If the example itself does not fit on a single page of output, it will be broken 
anyway. 


WIDE 


Specifies that the width of the example exceeds the document's default width 
for text. Depending on the document type, this argument can be interpreted 
as follows: 


e If the document style contains a left margin area that is normally used for 
headings, the ene s width will span that area as well as the normal 
text area. 


e If the document uses a multicolumn format, multicolumn output is 
suspended while the example is processed. The example is output and 
multicolumn output is then restored. 


e If the document style provides a range of sizes and styles for examples, 
this argument may be interpreted to mean that a specific size should be 
used for the example. 


<INTERACTIVE> 


MAXIMUM 


Can be used in conjunction with WIDE to indicate that the example may 
require additional adjustment to fit within the bounds of the text page. 
This argument must be used with discretion, and may not be suitable in all 
document styles. 








related tags “ =o? 
® <U> 

restrictions Indexing tags (<x> and <yY> tags) are not permitted within interactive 
examples. 


Tab characters cannot be used to format interactive examples; use spaces 
instead. 


Do not use text element tags within interactive examples (for example, <P>, 
<LIST> , Or <NOTE> .) 





required <ENDINTERACTIVE> 
terminator 





DESCRIPTION The <INTERACTIVE> tag indicates the beginning of an example dialog 
between user and system. It enables the tags <S> and <U>. 





EXAMPLE 


<P>If you do not specify the full command line, DCL will prompt 

you for the missing information. For example, if you do not specify an 
input file and an output file when you enter the COPY command, you will 
be prompted as follows: 


<INTERACTIVE> 

<S>($ )<U> (COPY) 

<S>($_From: )<U> (INTERACT . GNC) 
<S>($_To: ) <U> (NEWF ILE. GNC) 
<ENDINTERACTIVE> 


Note that you should specify whatever space follows the system prompt 
within the <S> tag. This example may produce the following output. 


If you do not specify the full command line, DCL will prompt you for the 
missing information. For example, if you do not specify an input file and an 
output file when you enter the COPY command, you will be prompted as 


follows: 
$ COPY 
$_From: INTERACT .GNC 
$_To: NEWFILE. GNC 


<KEEP> 


<KEEP> 


Specifies that a string of text should always occur on the same line of 
output, that is, should not be hyphenated between lines. 





FORMAT <KEEP> (text) 





ARGUMENTS text 


Specifies the text string to be kept on the same line of output. 





related tags e The following tags are used in conjuction with <KEEP> to allow a user 
to specify formatting attributes: 


<EMPHASIS> 
<DEFINE_SYMBOL> 
<HYPHENATE> 








restrictions None. 
required None. 
terminator 





DESCRIPTION Specifies that a string of text should always occur on the same line of output, 
that is, should not be hyphenated between lines. 





EXAMPLES 


Ef] <def ine_symbo1>(VAX11\<keep> (VAX--11)) 


This defines a text element symbol-name using an en dash and specifies that 
the line should not break between the en dash and the 11 in the reference 
<REFERENCE> (vax11). 


A reference to this defined symbol would produce the following output: 
VAX-11 

12) ’ <define_symbol>(product\<keep>(<emphasis>(VAX DOCUMENT\smallcaps) )) 
In this example, a symbol-name (“product”) is defined so that 


<REFERENCE> (product) always outputs the term “VAX DOCUMENT” in © 
small capital letters. 


A reference to this defined symbol-name would produce the following output: 


VAX DOCUMENT 
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<KEYWORD> 


<KEYWORD> 


Labels a significant word that deserves to be distinguished typographically. 





FORMAT 


<KEYWORD> (word) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


word 
Specifies the word to be distinguished. 





bd <VARIABLE> 


be <SPECIAL_NAME> 





None. 








DESCRIPTION 


The <KEYWORD> tag labels a word or term that you want to distinguish 
typographically. The default action of the <KEYWORD> tag outputs the 
keyword in boldface. From the point of view of formatted result, the 
<KEYWORD> tag may appear similar to the <EMPHASIS> tag with the 
BOLD argument. However, by using separate tags to label different kinds of 
information, the book designer is free to change the format of any one kind 
without affecting the others. 


What constitutes a keyword is something about which both editor and writer 
must agree. The presence of keywords must be taken into account in the 
book design. Use of the <KEYWORD> tag should be consistent within a 
document and across a document set. 





EXAMPLE 


<P>A <KEYWORD>(field) is a set of contiguous bytes in a logical record. 


This example may produce the following output: 


A field is a set of contiguous bytes in a logical record. 
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<LE> 


<LE> 


Labels a list element. 





FORMAT 


<LE> [(callout-number)] 





ARGUMENTS 


related tags 
restrictions 


required 
terminator 


callout-number 

Used only within the context of <LIST> (CALLOUT) to set the callout 
number identifying the list element. See the examples in the discussion of 
<LIST> (CALLOUT). 





° <LIST> 





Must be used within the context of a list tag. 





None. 





DESCRIPTION The <LE> tag identifies a list element and is only valid when used within 


the context of any of the <LIST> tags. 





EXAMPLES 
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See the examples in the discussion of the <LIST> tag. 


<LINE> 


<LINE> 


Specifies that the text that follows is to be placed on a new line of output. 





FORMAT INDENT \ unit-number] 
| <LINE> /( | BIGSKIP )] 
SMALLSKIP 





ARGUMENTS INDENT 
Specifies that the next line or block of text is to be indented from the 
preceding text. If this argument is specified, the next argument must be 
a numeric value in the range of 1 to 3, indicating the number of units 
(determined by the document design) the text is to be indented. 


The default value is 1. The maximum value is.9. 


BIGSKIP 
SMALLSKIP 


Specifies that a set amount of vertical space is to precede the element 
identified as a line or block of text. The actual amount of space created is 
determined by the document's design. 





related tags ¢ = <FINAL_CLEANUP> 
e = <CENTER—LINE> 


° <RIGHT_LINE> 








restrictions Invalid in monospaced examples and math. 
required None. 
terminator 


DESCRI PTION The result produced by this tag differs according to whether it is used in the 
context of a <P> tag, a <TABLE_ROW> tag, ora <FORMAT> tag: 


When you specify <LINE> in the context of a paragraph of text or a list 
element, the <LINE> tag causes the current paragraph to be terminated 
and then starts a new block of text. By default, the text block is not 
preceded by any extra vertical space nor is it indented. 


When you specify the <LINE> tag in the context of a <TABLE_ROW> or 
a <FORMAT> tag, the <LINE> tag causes the next text to begin on a new 
line of output, but does not modify the current paragraph. 
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<LINE> 


Do not use the <LINE> tag in a paragraph to cause the text formatter to 
break a line within the paragraph. Breaking a line to override a specific 
line break is a final formatting/cleanup instruction and you should use the 
<FINAL_CLEANUP> (LINE_BREAK) tag for this. 





EXAMPLES 


f] 9 <LIST> (NUMBERED) 
<le>ITEM 
<LINE>This item specifies... 


The output may be formatted as follows: 


1 ITEM 
This item specifies . .. 


¥] <P>This is a normal paragraph. 
<line>(INDENT\1\SMALLSKIP) 
This is a block paragraph, indented with skip. 


This may produce: 
This is a normal paragraph. 
This is a block paragraph, indented with skip. 


3 <P>Flashy designs are inappropriate for software manuals or for 
any serious or formal books because they do not reflect the 
intention of the writer. The purpose of any book design is 
<LINE> 
to clarify what the author is conveying, to translate the text 
attractively as print on a page, to communicate the message 
visually in harmony with the ideas. 


This output illustrates misuse of the <LINE> tag for formatting within a 
paragraph. Although correct results may be obtained on a given output 
device for a particular run of a file, the output may also be formatted as 
follows: 


Flashy designs are inappropriate for software manuals or for any serious or 
formal books because they do not reflect the intention of the writer. The 
purpose of any book design is 


to clarify what the author is conveying, to translate the text attractively as 
print on a page, to communicate the message visually in harmony with the 
ideas. 
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<LINE> 


<TABLE>(Card Reader Errors: Causes and Corrective Actions\cardread_tab) 
<TABLE_ATTRIBUTES> (wide\multipage) 

<TABLE_SETUP> (3\12\21) 

<TABLE_HEADS> (Error\Causes\Corrective Action) 

<TABLE_ROW>(READ CHECK\Card edges torn <LINE> Punch in column 0 

or 81\Remove the faulty card from the output stacker, duplicate the card, place 
it in the input hopper, and press the <EMPHASIS>(RESET\bold) button.) 
<TABLE_ROW_BREAK> (FIRST) 

<TABLE_ROW>(PICK CHECK\Damage to leading edge <LINE> Torn webs 

<LINE> Cards 

stapled together\Remove the card from the input hopper, duplicate 

the faulty card, place the card back in the input 

hopper, and press the <EMPHASIS>(RESET\bold) button.) 
<TABLE_ROW_BREAK> (LAST) 

<TABLE_ROW> (STACK CHECK\Jam in the card track <LINE> Badly mutilated card 
\Correct the jam and/or remove the mutilated card from the output stacker, 
duplicate the card, place it in the input hopper, and press the 
<EMPHASIS>(RESET\bold) button.) 

<TABLE_ROW>(HOPPER CHECK\Input hopper empty <LINE> Output stacker full\Load 
the input hopper. <LINE> Unload the output stacker.) 

<ENDTABLE> 


This example shows the use of the <LINE> tag in a three-column table. It 
may produce the following output: 


Table x—x Card Reader Errors: Causes and Corrective Actions 


Error Causes Corrective Action 
READ CHECK Card edges torn Remove the faulty card from the output stacker, 
Punch in column O or 81 duplicate the card, place it in the input hopper, and 
press the RESET button. 
Damage to leading edge. Remove the card from the input hopper, duplicate 


PICK CHECK 
STACK CHECK 


HOPPER CHECK 


Torn webs 
Cards stapled together 


Jam in the card track 
Badly mutilated card 


Input hopper empty 
Output stacker full 


EG} = <FORMAT>(MY COMMAND) 


<FCMD>( ) 


<FPARMS>(one parameter<line>two<line>three) 


<ENDFORMAT> 


the faulty card, place the card back in the input 
hopper, and press the RESET button. 


Correct the jam and/or remove the mutilated card 
from the output stacker, duplicate the card, place it 
in the input hopper, and press the RESET button. 


Load the input hopper. 
Unload the output stacker. 


This example shows the <LINE> tag in a <FORMAT> tag. This example may 
produce the following output: 





MY 


COMMAND 


one parameter 


two 
three 
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<LINE_ART> 


<LINE_ART> 


Labels a rough sketch produced at the terminal keyboard for draft output, 
to give some idea of what the final figure will look like. 





FORMAT 


[KEEP] 
SLINE_ART> [0 per, MAXIMUM] 7! 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 
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KEEP 


Specifies that the line art is not to be broken across pages, that is, if the line 
art does not fit on the current page, it will be placed on the next page. If the 
line art itself does not fit on a single page of output, it will be broken anyway. 


WIDE 


Specifies that the width of the line art exceeds the document’s default width 
for text. Depending on the document type, this argument can be interpreted 
as follows: 


e If the document style contains a left margin area that is normally used for 
headings, the line art’s width will span that area as well as the normal 
text area. 


If the document uses a multicolumn format, the line art will result in 
suspension of multicolumn output while it is being processed. The line 
art will be output, and then multicolumn output will be restored. 


If the document style provides a range of sizes and styles for examples, 
this argument may be interpreted to mean that a specific size should be 
used for the line art. 


MAXIMUM 


Can be used in conjunction with WIDE to indicate that the line art might 
require additional adjustment to fit within the bounds of the text page. 
This argument must be used with discretion, and may not be suitable in all 
document styles. 





° <FIGURE> 


. <VALID_BREAK> 





Only used within the context of <FIGURE> and <ENDFIGURE> tags. 


Note that the results of keyboard drawing may be adequate for draft 
purposes, but will not be acceptable in the context of laser printer output. 





<ENDLINE_ART> 


<LINE_ART> 





DESCRIPTION The <LINE_ART> tag labels a rough sketch produced at the terminal 
k 


eyboard for draft output, to give some idea of what the final figure will 
look like. 





EXAMPLE 


See the examples in the discussion of the <FIGURE> tag. 
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<LIST> 


<LIST> 


Begins a list. The type of list (for example, numbered or stacked) is 
specified by the argument to the <LIST> tag. 





FORMAT <LIST> (keyword \ attributes]) 





ARGUMENTS KEYWORD 
Specifies the type of list. 


ALPHABETIC The list element identifiers are alphabetic letters. 
ONS Ce apt? a” — CALLOUT The list element identifiers.are reverse-print callout numbers 
punt ge vs, (on supported output devices), for example ©. 

NUMBERED The list element identifiers are Arabic numerals. 

ROMAN The list element identifiers are Roman numerals. 

SIMPLE There are no list element identifiers. 

STACKED Individual list elements do not have identifiers, but the entire 


list is stacked within the specified set of delimiters (braces, 
brackets, double brackets, or single or double vertical rules). 


( ba thtor *) UNNUMBERED List element identifiers are special characters. 
ATTRIBUTES 


Specifies the attributes of the list element identifiers. More than one attribute 
can be specified. 


Start-letter For an ALPHABETIC list. Specifies the alphabetic letter to 
use for the first item in the sequence. Subsequent items 
are automatically incremented. 


Uppercase For an ALPHABETIC or ROMAN list. Specifies that 
the list element identifiers (alphabetic letters or roman 
numerals) are to be printed in uppercase letters. By 
default, alphabetic and Roman numeral list element 
identifiers are printed using lowercase letters. 


Start-number For a NUMBERED or ROMAN list. Specifies the number 
to be assigned to the first list element. Subsequent list 
elements are automatically incremented. 


BRACES For a STACKED list. Each attribute for a STACKED list 
BRACKETS specifies the delimiter to be used to surround the stacked 
DOUBLE _— elements. If no keyword is specified, list elements are 
BRACKETS stacked without a surrounding delimiter. 


VERTICAL _RULE 
DOUBLE—VERTICAL _RULE 


Char For an UNNUMBERED list. Specifies a single character or 
a tag that results in a single printed character of output 
that will be used to indicate list elements. If char is not 
specified, the bullet character is used. 
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related tags 
restrictions 


required 
terminator 


<LIST> 





° <LE> 





Only used in the context of a paragraph or table. 





<ENDLIST > 





DESCRIPTION 


The <LIST> (ALPHABETIC), <LIST> (NUMBERED), and <LIST> (roman) 
tags begin a list whose elements have a particular sequence or priority. Use 
the UNNUMBERED or SIMPLE arguments to begin a list that has no inherent 
order or priority. 


Alphabetic lists are useful nested within numbered lists. A numbered list is 
used to indicate a particular sequence or priority within the list elements. 


The SIMPLE argument labels a simple list with no enumerator or special 
character preceding each list element. 


The STACKED argument begins a list whose elements are left-justified 

on successive lines of an imaginary box. The box can have large braces 

or brackets placed on each side. The box is then centered vertically so 

that it aligns with text to the left or right on the same line. (By contrast, 
<LIST> (SIMPLE) terminates the current paragraph and indents the list, 

so that it is seen as a separate entity from the text above and below it.) 
<LIST> (STACKED) is especially useful for showing syntactic elements with a 
<FORMAT> tag. | 


The UNNUMBERED argument labels lists that have no particular order or 
priority within the list element. Normally a bullet is the character used before 
each list element. You can specify another character by passing it as an 
argument. 
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<LIST> 





EXAMPLES 


<LIST> (NUMBERED) 
<LE>Review doc plan 
<LE>Find out these numbers: 
<LIST> (UNNUMBERED) 
<LE>LPN 
<LE>DPN 
<LE>order number 
<ENDLIST> 
<LE>For revisions of books not already in the library, have 
production or the writer rename the file 
according to its new LPN. 
<LE>Open a library for the book if none exists (except for 
one-shot jobs). 
<LIST> (ALPHABETIC) 
<LE>Decide with writer about timing: 
<LIST> (UNNUMBERED) 
<LE>Must be done before final production. 
<LE>Shouldn’t be done until text is stable. 
<LE>Preferred time is at major edit pass. 
<ENDLIST> 
<LE>Cooperate with production librarian on paperwork. 
<LE>Help writers name new element files correctly. 
<LE>Verify that all files are of the same file type. 
<LE>For a revision, be sure files are renamed using the 
revision’s LPN when the library is created for the revision. 
<ENDLIST> 
<ENDLIST> 


In this example, the first nested list has no particular sequence. The second 
nested list does have an order to it and this order is reflected in the use of the 


<LIST> (alphabetic) tag. 
This example may produce the following output: 
1 Review doc plan 
2 Find out these numbers: 
e LPN 
e DPN 


e order number 


3 For revisions of books not already in the library, have production or the 


writer rename the file according to its new LPN. 


4 Open a library for the book if none exists (except for one-shot jobs). 


a. Decide with writer about timing: 
e Must be done before final production. 
e Shouldn’t be done until text is stable. 


e Preferred time is at major edit pass. 


Help writers name new element files correctly. 


Verify that all files are of the same file type. 


® 29 5 


when the library is created for the revision. 
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. Cooperate with production librarian on paperwork. 


For a revision, be sure files are renamed using the revision’s LPN 


<LIST> 


<P>Items e and f describe the $GETJPI AST activity: 

<LIST> (ALPHABETIC\5) 

<LE>An ACB is constructed for a special kernel AST. 

<LE>When the special kernel mode AST routine executes in the context of 

the target process, the requested information is moved into the system buffer. 
The ACB is then reset to deliver a special kernel mode AST back to the 
requesting process. 

<ENDLIST> 


This example may produce the following output: 
Items e and f describe the $GETJPI AST activity: 
e. An ACB is constructed for a special kernel AST. 


f. When the special kernel mode AST routine executes in the context of the 
target process, the requested information is moved into the system buffer. 
The ACB is then reset to deliver a special kernel mode AST back to the 
requesting process. 


<P>At this point, you can log in to the system as the system manager 

by performing the following steps at the console terminal: 

<LIST> (NUMBERED ) 

<LE>Press RETURN. 

<LE>In response to the system’s request for your user name, type SYSTEM. 
<LE>In response to the system’s request for your password, type MANAGER. 
<ENDLIST> 


This example produces the following output: 


At this point, you can log in to the system as the system manager by 
performing the following steps at the console terminal: 


1 Press RETURN. 
2 In response to the system’s request for your user name, type SYSTEM. 


3 In response to the system’s request for your password, type MANAGER. 


<P>Items six and seven describe two main principles of a generic 

markup language: 

<LIST> (NUMBERED \6) 

<LE>Descriptive markup predominates and is distinguished from processing 
instructions. 

<LE>Markup is formally defined for each type of document. 

<ENDLIST> 


This example shows how you can cause a numbered list to begin 
with a specified number by passing the number as an argument to the 
<LIST> (NUMBERED) tag. This example has the following output: 


Items six and seven describe two main principles of a generic markup 
language: 


6 Descriptive markup predominates and is distinguished from processing 
instructions. 


7 Markup is formally defined for each type of document. 
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<LIST> 


5) <P>The following items are needed: 


<LIST> (SIMPLE) 
<LE>bread 
<LE>milk 
<LE>cheese 
<LE>cereal 
<LE>fruit 
<ENDLIST> 
This example produces the following output: 
The following items are needed: 
bread 
milk 
cheese 
cereal 
fruit 
<P> , 
ON <LIST>(stacked\braces) 
<LE>ANYCONDITION 


<LE>ENDFILE (reference) 
<LE>ENDPAGE (reference) 
<LE>F INISH 
<LE>KEY (reference) 
<LE>UNDEFINEDFILE (reference) 
<LE>ERROR 
<LE>F IXEDOVERFLOW 
<LE>OVERFLOW 
<LE>UNDERF LOW 
<LE>VAXCONDITION (expression) 
<LE>ZERODIVIDE 

<ENDLIST> 


<LIST>(stacked\braces) 
<LE>statement 
<LE>begin-block 
<ENDLIST> 


Notice that the tags are indented to help in visually checking the matching of 
the <LIST> (stacked) and <ENDLIST> tags. This indentation has no effect on 
the output, however. This example may produce the following: 


ANYCONDITION 
ENDFILE(reference) 
ENDPAGE(reference) 
FINISH 
KEY(reference) 


ON UNDEFINEDFILE(reference) { statement 


ERROR 

FIXEDOVERFLOW 
OVERFLOW 

UNDERFLOW 
VAXCONDITION(expression) 
ZERODIVIDE 
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begin-block 


<LIST> 


<P> 
OPEN FILE (reference) [TITLE(expression)] 
<P> 
<LIST>(stacked\brackets) 
<LE>[STREAM] <LIST>(stacked\brackets) 
<LE> [INPUT] 
<LE>QUTPUT [LINESIZE] (integer) {PRINT [PAGESIZE(integer) } ] 
<ENDLIST> 
<LE>RECORD <LIST>(stacked\brackets) 
<LE> [INPUT] 
<LE>OUTPUT 
<LE>UPDATE 
<ENDLIST> 
<LIST> (stacked\brackets) 
<LE>DIRECT 
<LE> [SEQ [UENTIAL] ] 
<ENDLIST> 
[KEYED] 
<ENDLIST> 


This example shows nesting of the <LIST> (stacked) tags. This example may 
produce the following: 


OPEN FILE (reference) [TITLE(expression)] 








[INPUT] 

eTREAM| | OUTPUT [LINESIZE|(integer) [PRINT [PAGESIZE(integer)] ] 
[INPUT] DIRECT 

RECORD | OUTPUT | | tkeveny 
OUTPUT | | [SEQUENTIAL] 


<TABLE> 
<TABLE_SETUP> (2\20) 
<TABLE_HEADS>(Some stacked\Stuff in a Table) 
<TABLE_ROW>(<LIST> (stacked\braces) 
<LE>one 
<LE>two 
<LE>three 
<ENDLIST>\That was stacked in a table.) 
<TABLE_ROW>(Just a second item\<LIST>(stacked\braces) 
<LE>one 
<LE>two 
<LE>three 
<ENDLIST>) 
<TABLE_ROW>(this is the last item) 
<ENDTABLE> 


Here, <LIST> (stacked) arguments are used within a table. Again, the generic 
code is indented simply as an aid for visually checking the nesting of tags. 
This example may produce the following: 


Some stacked Stuff in a Table 
one That was stacked in a table. 
two 
three 
Just a second item Ons 
two 
three 


this is the last item 
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-<LIST> 


2 


9) <P>To create a system that more closely suits the requirements of 
your site, you can do any of the following: 
<LIST> (UNNUMBERED) 
<LE>Select a default bootstrap command procedure 
<LE>Modify system parameters for special hardware configuration needs or 
special workload requirements 
<LE>Perform other site-specific modifications 
<ENDLIST> 


This example may produce the following output: 


To create a system that more closely suits the requirements of your site, you 
can do any of the following: 


¢ Select a default bootstrap command procedure 


¢ Modify system parameters for special hardware configuration needs or 
special workload requirements 


e Perform other site-specific modifications 


10) <P>To create a system that more closely suits the requirements of 
your site, you can do any of the following: 
<LIST> (UNNUMBERED \ +) 
<LE>Select a default bootstrap command procedure 
<LE>Modify system parameters for special hardware configuration needs or 
special workload requirements 
<LE>Perform other site-specific modifications 
<ENDLIST> 


This example shows how you can specify a character other than a bullet to 
label each list element. This example may produce the following output: 


To create a system that more closely suits the requirements of your site, you 
can do any of the following: 


+ Select a default bootstrap command procedure 


+ Modify system parameters for special hardware configuration needs or 
special workload requirements 


+ Perform other site-specific modifications 
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<LITERAL> 


<LITERAL> 


Allows you to specify text that contains words in angle brackets that 
might otherwise be interpreted as tags. 





FORMAT <LITERAL> (literal-text) 
or 


<LITERAL> 
literal-text 


<ENDLITERAL> 


ARGUMENTS _/iteral-text 


The literal text to be passed through the tag translator unprocessed. 

















related tags None. 

restrictions None. 

required <ENDLITERAL> —Required if the text is not specified as an argument. 
terminator 

EXAMPLE 


<P> I’ve experimented with my own method for noting questionable 
phrases, by placing <LITERAL><NOTE_PROBLEM><ENDLITERAL> near the 
phrase. 


This example may have the following output: 


I’ve experimented with my own method for noting questionable phrases, by 
placing <NOTE_PROBLEM> near the phrase. 
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<LOWERCASE> 





<LOWERCASE> 


Labels text that should appear as lowercase in the final output. 





FORMAT <LOWERCASE> (text) 





ARGUMENTS text 


Specifies the text to appear in lowercase. 











related tags ©  <UPPERCASE> 
restrictions None. 

required None. 
terminator 





DESCRIPTION [In your book, there may be a text element, such as a heading, that normally 
appears in uppercase. For example, in some book designs, first-level headings 
use all uppercase letters. 


You may encounter a situation where you need to overcome the default case 
in one of your tags and ensure that the result in the final output appears in 
lowercase. The <LOWERCASE> tag allows you to do this. 





EXAMPLE 


<HEAD2>(HeRe iS aN ExAmP1E oF <LOWERCASE>(10wErCaSe) tExT) 


In this example, assume that the doctype being used causes the tag <HEAD2> 
to output a heading that is in uppercase, no matter what the case of the text 
passed to it. 


The example may produce the following output: 
HERE IS AN EXAMPLE OF lowercase TEXT 


The default to uppercase letters causes the heading to be uniformly uppercase, 
with the exception of the text passed to the <LOWERCASE> tag. 


<MARK> 





<MARK> 


Indicates the beginning of new or modified information. 





FORMAT <MARK> 





ARGUMENTS = None. 





related tags ©  <REVISION> 
¢  <UPDATE_RANGE> 





restrictions Output is enabled only if the <REVISION> tag has been specified. 





required <ENDMARK> 
terminator 





DESCRIPTION The <MARK> and <ENDMARK> tags delimit a sequence of text that has 
been modified. These tags will produce vertical bars in the margin of the 
document. 


Make sure to place the <MARK> and <ENDMARK> tags next to the text 
they mark, without preceding or following the text with other tags. The text 
formatter interprets <MARK> based on the last text character encountered 
before the <MARK> tag. 





EXAMPLE 


<P> 

The following characters are legal in “MACRO-11 source programs: 
<LIST> (NUMBERED ) 

<LE>The letters A through Z. Both upper- and lowercase letters are 
acceptable, although, upon input, lowercase letters are converted to 
uppercase. 

<LE>The digits 0 through 9. 

<LE>The characters period <PARENDCHAR>(.) and dollar sign 
<PARENDCHAR>($). These characters are reserved for use as Digital 
Equipment Corporation system program symbols. 

<ENDLIST> 
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<MARK> 


<REVISION> 


<P> 

The following characters are legal in MACRO-11 source programs: 
<LIST> (NUMBERED) 

<LE>The letters A through Z. Both upper- and lowercase letters are 
acceptable, although, upon input, lowercase letters are converted to 
uppercase. 


<MARK> 

<LE>Characters in the DEC multinational character set (MCS). A chart 
showing the MCS is located in <REFERENCE>(mcs_app) , 

with a list of directives that 

support the MCS. 

<ENDMARK> 


<LE>The digits O through 9. 

<LE>The characters period <PARENDCHAR>(.) and dollar sign 
<PARENDCHAR>($). These characters are reserved for use as Digital 
Equipment Corporation system program symbols. 

<ENDLIST> 


In this example, the first paragraph is the original and the second paragraph 
is the modified version with the <MARK> and <ENDMARK> tags coded in. 
The formatted output for the original paragraph and the modified paragraph 
may be as follows: 


The following characters are legal in MACRO-11 source programs: 


1 The letters A through Z. Both upper- and lowercase letters are acceptable, 
although, upon input, lowercase letters are converted to uppercase. 


2 The digits 0 through 9. 


3 The characters period (.) and dollar sign ($). These characters are 
reserved for use as Digital Equipment Corporation system program 
symbols. 


The following characters are legal in MACRO-11 source programs: 


1 The letters A through Z. Both upper- and lowercase letters are acceptable, 
although, upon input, lowercase letters are converted to uppercase. 


2 Characters in the DEC multinational character set (MCS). A chart showing 
the MCS is located in Appendix A, with a list of directives that support 
the MCS. 


3 The digits 0 through 9. 


4 The characters period (.) and dollar sign ($). These characters are 
reserved for use as Digital Equipment Corporation system program 
symbols. 
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<MATH> 


<MATH> 


Labels a short mathematical expression or the beginning of an extended 
mathematical example. 





FORMAT { math-expression 
Se ({ DISPLAY/ \ symbol-name] \ 





ARGUMENTS '- math-expression 


Specifies a mathematical expression to be included in the text of a sentence or 
paragraph. 


DISPLAY 


Specifies a keyword indicating that an extended mathematical equation or 
expression is to be set off from the surrounding text. 


symbol-name | 

Specifies a symbol-name by which the extended mathematical equation is to 
be referenced. If this argument is specified, the equation is assigned a number 
and the number is printed to the right of the equation. 


Symbol-names must not exceed 31 characters, and must only contain 
alphabetic letters, numbers, or underscores in them. Do not begin a symbol- 
name with an underscore. 


Once the symbol-name is defined, the equation can be referenced using the 
<REFERENCE> tag. 





related tags ¢ = <MATH_CHAR> 
bd <CODE_EXAMPLE> 


e The SOFTWARE doctype <DISPLAY> tag 





restrictions ¢ The use of extended mathematical examples is not valid within tables or 
monospaced examples. 


The set of tags valid within a mathematical expression is limited to those 
listed in the tables in the Description section. 





required <ENDMATH> —Required when DISPLAY is specified as an argument to 
terminator Seas 


<MATH> 





- DESCRIPTION 
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Note: 


Within an argument to <MATH> or within the bounds of 

<MATH> (DISPLAY) .... <ENDMATH> , you can specify simple or complex 
mathematical expressions, according to the rules outlined below. The context 
in which you enter text and tags within a mathematical expression is severely 
restricted. 


In a mathematical expression, all formatting is controlled by the text 
processor. When you use the keyword DISPLAY, the output will be 
offset from the surrounding text, but you do not have any control over its 
positioning. Furthermore, blank spaces and carriage returns are ignored; 
the text processing program assumes that all text strings are mathematical 
variable names, and makes all decisions regarding the output formatting. 


Simple Expressions 


The following tags are used to indicate simple binary operations. In the 
context of a mathematical expression, you can use either the tag name or the 
function’s symbol. 


<TIMES> * Multiplication 


<PLUS> + Plus 
<MINUS> - Minus 
<DIVIDED_BY > / Division 
<EQUALS> 7 Equality 


For example, the following are equivalent: 


<MATH> (total = A+B -C#*D / E) 
<MATH> (total <EQUALS> A <PLUS> B <MINUS> C <TIMES> D <DIVIDED_BY> E) 


Both produce the output: total = A+B—C*D/E 


Note that operators are evaluated using the normal mathematical rules for 
precedence of operators. You can control the evaluation using the <GROUP> 
tag. For example: 


<MATH> (total = <group>(A + B - C * D) / E) 


This produces: total = A+ B-—C*D/E 


The use of any nonalphanumeric characters other than those specified 
above in the context of math may produce unpredictable results, including 
errors from the text formatter. 


The effect of the <GROUP> tag is supplied by default for fractional 
expressions when you use the <FRACTION> tag: 


<MATH> (display) 
total = <FRACTION>(A + B - C * D\E) 
<ENDMATH> 


Variable Names 


The text formatter assumes that variable names are primarily alphabetic letters 
or specia: characters represented by the <MATH_CHAR> tag. If you need to 
specify any variable names in expressions that contain special characters, you 
must use the <VARIABLE> or <TEXT> tags. For example: 


<MATH> (<variable>(event_flag) = 1) 


<MATH> 


If you require multiword variable names, you must use the <SP> tag to 
indicate spacing: 


<MATH> (display) 
<VARIABLE> (SUCCESS<sp>RATE) <equals> 
<group>( 
<VARIABLE>(TOTAL<SP>HITS) <over>(<VARIABLE>(TOTAL<sp>HITS) <plus> 
<VARIABLE>(TOTAL<sp> MISSES) <plus> 
<VARIABLE> (TOTAL<sp>IND) 
) 


) 4 
<times> 100 
<ENDMATH> 


To produce: 


TOTAL HITS 


ee es TOTAL HITS + TOTAL MISSES + TOTAL IND oo 


You can provide special annotation for variable names using one of the 
following: 


Tag Output 
<BAR_CHAR> (x) zr 
<DOT_CHAR> (x) £ 
<HAT> (xyz) Lyz 
<HAT_CHAR> (x) £ 
<OVERLINE> (var) var 
<TILDE> (xyz) Lyz 
<TILDE_CHAR> (x) zr 
<UNDERLINE > (var) var 
<VECTOR> (x) z 
Parentheses 


Most of the tags valid in math do not accept arguments. However, 
parentheses are frequently used in mathematical expressions. You must 
be careful, therefore, to use spaces preceding the parentheses. For example: 


<MATH>(A <minus> (B<PLUS>C)) 


Summary of Tags 


Table 9-3 summarizes the tags that are valid in mathematical expressions. 
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<MATH> 
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Table 9-3 <MATH> Expressions 
Tag Operation and Output 
< AMPERSAND > Specifies a literal ampersand character 
in a math expression. 
<BACKSLASH> Specifies a literal backslash character in 
a math expression. 
<CASES> Specifies a case construction. See 
<CASE_ROW> “Matrices and Cases.” 
<ENDCASES > 
<CDOTS> Specifies centered dots, as in ---. 


<CHOOSE> (expression 1\expression2) 
<DDOTS> 


<DIVIDED_BY > 

<DOTS> 

<DOT_TIMES> 

<EQUALS> 

<FRACTION> (numerator\denominaton 


<FUNC> (expression) 
<GROUP> (expression) 


<INTEGRAL> 
<INTEGRAL _LIMITS> 


<MATRIX> 
<MATRIX_ROW > 
<ENDMATRIX> 


<MINUS> 
<MOD> 
<LBAR> 


<LBRACE> 


<LBRACKET > 


<LCEIL> 


<LFLOOR> 


Parenthetical notation, as in (7). 


Specifies diagonal dots, as in © 
Division, as in a/b. 

Specifies horizontal dots, as in.... 
Multiplication, as in a- b. 

Equality, as in a = b. 


Specifies a fraction, as in 
<MATH> ({a\over b}). 


Function, as in af (b). 


Provides control over the order of 
operation. See the “Examples,” below. 


us 
Specifies an integral, as in [2 


Specifies an integral in displayed math. 
See “Superscript and Subscripts.” 


Specifies a matrix. See “Matrices and 
Cases.” 


Minus, as in a — b. 
Modulo, as in n mod p. 


Begins an expression delimited 
with vertical bars. See “Delimited 
Expressions.” 


Begins an expression delimited 
with curly braces. See “Delimited 
Expressions.” 


Begins an expression delimited with 
square brackets. See “Delimited 
Expressions.” 


Begins an expression delimited with 
ceil characters ({). See “Delimited 
Expressions.” 


Begins an expression delimited with 
floor characters (|). See “Delimited 
Expressions.” 


<MATH> 


Table 9-3 (Cont.) <MATH> Expressions 








Tag Operation and Output 

<LPAREN> Begins an expression delimited . 
with parentheses. See “Delimited 
Expressions.” 

<PMOD> Parenthetical mod, as ina (mod p). 

<OVER> (expression) Division, as in ¢. 

<PI> The pi character, 7. 

<PLUS> Plus, as ina+ 0. 

<RBAR> Ends an expression delimited 
with vertical bars. See “Delimited 
Expressions.” 

<RBRACE> Ends an expression delimited with curly 
braces. See “Delimited Expressions.” 

<RBRACKET> Ends an expression delimited with 
square brackets. See “Delimited 
Expressions.” 

<RCEIL> Ends an expression delimited with 
ceiling characters (]). See “Delimited 
Expressions.” 

<RFLOOR> Ends an expression delimited with 
floor characters (|). See “Delimited 
Expressions.” 

<RPAREN> Ends an expression delimited 
with parentheses. See “Delimited 
Expressions.” 

<SP> Provides space in a variable name or 


<SQRT> (expression) 
<SUBSCRIPT> (expression) 
<SUM> 


<SUM_NOLIMITS> 


<SUPERSCRIPT> (expression) 
<TEXT> 

<TIMES> 

<TO> 

<VARIABLE > 


<VDOTS> 


<VECTOR> (var 
<X_TIMES> 


expression. 
The square root, as in av/b. 
Subscription, as in ap. 


Summation, as in a>-b. See 
“Superscripts and Subscripts”. 


Summation, as in a>_b. See 
“Operators with and Without Limits.” 


Exponentiation, as in a°. 
Specifies text in a math expression. 
Multiplication, as in a x 6. 
Indicates progression, as in 1 — 10. 


Specifies a variable name that contains 
nonalphanumeric characters. 


Specifies vertical dots, as in .. 
A vector, as in Z. 


Multiplication, as in a x b.. 
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Subscripts and Superscripts 


When you specify <SUBSCRIPT> and <SUPERSCRIPT> tags, the super- or 
subscription applies to the immediately preceding variable or expression. 
They can be specified in any order. Thus, 

<MATH> (a<subscript>(2)<superscript>(n-1)) 


Produces: a 


In extended mathematical expressions, the <SUPERSCRIPT> and 
<SUBSCRIPT> tags produce different, special results in conjunction with 
the <SUM> and <INTEGRAL> functions and their complementary tags 
<SUM_NOLIMITS> and <INTEGRAL_LIMITS>. For example: 

<MATH> (display) 

<sum><subscript> (n=1)<superscript>(m) 


<sum_nolimits><subscript>(n=1)<superscript>(m) 
<ENDMATH> 


By default, the <SUM> tag places the superscript and subscript above and 
below the sum sign. <SUM_NOLIMITS> places them adjacent to the symbol: 


hs m 
aoa 
n=1 


The <INTEGRAL> and <INTEGRAL_LIMITS> work the same way. Note the 
differences in the following: 


<MATH> (display) 


<integral><subscript> (0) <superscript>(<pi><over>(2) ) 
<integral_limits><subscript>(0)<superscript>(<pi><over>(2)) 


<ENDMATH> 
x 
n 2 
0 
0 


Mathematical Functions 


In addition to the operations and special functions listed in Table 9-3, you 
can specify mathematical functions using any of the tags listed in Table 9-4. 
These tags all let you specify the tag with or without an argument. If you 
specify an argument, it is placed in parentheses following the function name. 
For example: 


<MATH> (<SIN>(d) ) 


This produces: sin(d). 


Table 9-4 Tags for Mathematical Functions 


Tag Function 
<ARCCOS> arccos 
<ARCSIN> arcsin 
<ARCTAN> arctan 
<ARG> arg 
<COS> cos 
<COSH> cosh 
<COT> cot 
<COTH> coth 
<CSC> csc 
<DEG> deg 
<DET> det 
<DIM> dim 
<EXP> exp 
<GCD> gcd 
<HOM> hom 
<INF> inf 
<KER> ker 
<LG> lg 
<LIM> lim 
<LIMINF> lim inf 
<LIMSUP > lim sup 
<LN> In 
<LOG> log 
<MAX> max 
<MIN> min 
<MOD> mod 
<PMOD> (mod n) 
<PR> Pr 
<SEC> sec 
<SIN> sin 
<SINH> sinh 
<SUP> sup 
<TAN> tan 

_ <TANH> tanh 


<MATH> 








9-145 


<MATH> 
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‘For example, the following: 


<LIST> (UNNUMBERED) 


<le><math> ( 
<sin>2<math_char>(theta) 
<equals>2<sin><math_char> (theta) <cos><math_char> (theta) 


) 


<le><math> ( 
O(n <log>n <log><log>n) 


) 


<le><math> ( 
<pr>(X >x)= <exp>(-x/<math_char> (mu) ) 


) 


<le><math> ( 
<max><subscript> (1<math_char>(geq) n<math_char>(geq)m) 
<log><subscript> (2) P<subscript>(n) 


) 


<le><math> ( 

<lim><subscript> (x<to>0) <group>( 
<sin>x<over>(x)) 

<equals>1 

) 

<ENDLIST> 


Produce: 

e = sin 20 = 2sin @ cos 0 

© O(nlog nlog log n) 

© Pr(X > 2) = exp(—z/p) 


© = MaX1>n>m log2 Ph 


sin x 


8 lim,_,9 nae 1 


Delimited Expressions 


To produce delimited expressions in mathematics, you must use one of the 
following pairs of tags: 


¢ <LBAR> and <RBAR> —for opening and closing vertical bars 
¢ <LBRACE> and <RBRACE> —for opening and closing curly braces 


¢ <LBRACKET> and <RBRACKET> —for opening and closing square 
brackets 


¢ <LCEIL> and <RCEIL> —for opening and closing ceiling delimiters 
¢ <LFLOOR> and <RFLOOR> —for opening and closing floor delimiters 


¢ <LPAREN> and <RPAREN> —for opening and closing parentheses.. 


The text formatter automatically assumes that text within these pairs is to be 
grouped, and it sizes the delimiters automatically. 


For example: 


<MATH> (display) 


‘<group>( 


C<subscript> (dg) 


<fraction>(<math_char> (partial) Q<subscript>(d)\ 
<math_char> (partial) V<subscript>(g) ) 


<MATH> 


-C<subscript>(oxt) 


[0.5 


+ 
<lparen>f<subscript>(0) DVG - 
<group>(2f<subscript>(0) V<subscript> (com) <over>(f<subscript>(1)) 


<rparen> 
<group>(1 <over>(f<subscript>(1)<superscript>(2))) 


<ENDMATH> 


This produces: 


Qa 


Cas = 5, 


= —Cozt }0.5 + (nove - “Loon es 


i Sf 


Matrices and Cases 


You can construct matrices and case constructs using the tags provided with 
<MATRIX> and <CASES>. 


The <MATRIX> tag has the format: 


BRACES 
<MATRIX> ( | BRACKETS ) 
VERTICAL _RULE 


Where the keywords BRACES, BRACKETS, and VERTICAL_RULE override 
the default matrix delimiter, parentheses. 


When you construct a matrix, each row in the matrix must be specified using 
the <MATRIX_ROW> tag. You can specify a maximum of nine columns for 
the row. The matrix must be terminated with the <ENDMATRIX> tag. For 
example: 


<matrix> (brackets) 
<matrix_row> (A) 
<matrix_row>(B) 
<matrix_row>(C) 
<matrix_row>(D) 
<endmatrix> 


This simple, one-column matrix may produce the following output: 


A 
B 
C 
D 


A more complex example shows the use of parentheses: 


<math> (display) 
<det><matrix>(vertical_rule) 
<matrix_row>(c<subscript>(0) \c<subscript>(1)\ 
c<subscript>(2) \<dots>\c<subscript>(n) ) 
<matrix_row>(c<subscript>(1)\c<subscript>(2)\ 
c<subscript>(3) \<dots>\c<subscript>(n+1)) 
<matrix_row> (c<subscript>(2) \c<subscript>(3)\ 
c<subscript>(4) \<dots>\c<subscript>(n+2) ) 
<matrix_row>(<vdots>\<vdots>\<vdots>\<vdots>) 
<matrix_row>(c<subscript>(n) \c<subscript>(n+1)\ 
c<subscript>(n+2)\<dots>\c<subscript>(2n) ) 
<endmatrix> > 0. 
<endmath> 


9-147 


<MATH> 


Would produce: 
Co Cy C2 sere Cn 
Cy C9 C3 see Cnt 
2 «6&3 C4 tes One? 
det > 0. 
Cn Cnsl. Cnt2 +++ ©2n 


<CASES> is similar to <MATRIX> , but it produces only a large left-hand 
brace; there is no closing delimiter. It is specified as: 


<MATH> (display) 

<cases> 
<case_row>(1/3\if\0> x\;) 
<case_row>(2/3\if\3< x\;) 
<case_row>(0O\elsewhere. ) 


<endcases> 

<ENDMATH> 

This might produce: 
1/3 if0> a2; 
2/3° if 3 < 3; 
0 elsewhere. . 





EXAMPLES 


The circumference of a circle is calculated using the 
formula <MATH>(c<equals><pi>r<superscript>(2)). 


This example illustrates a simple mathematical expression used in the text of a 
sentence. This example produces: “ The circumference of a circle is calculated 


using the formula ¢ = mr?.” 


<MATH> (DISPLAY) 
vsize <equals> psize <minus>(<minus>topglue) <minus> topdepth <minus> footerglue 
<ENDMATH> 


This example produces: 
usize = psize — (—topglue) — topdepth — footerglue 


Note that the parenthetical expression following the first <MINUS> tag must 
have a space in front of it; otherwise the expression will be interpreted as an 
argument to <MINUS>. 


<LIST> (NUMBERED ) 

<le><MATH> (1<over>(2)) 

<le><MATH> (n+1<over>(3)) 

<le><MATH> (<choose>(N+1\3)) 

<le><MATH> (<sum><subscript>(n=1)<superscript>(3)Z<subscript>(n)<superscript>(2) ) 
<ENDLIST> 


This list of simple inline expressions produces: 


1 3 

2 

3 ("3°) 

4 4% 
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<MATH> 


<MATH> (DISPLAY) 
<GROUP> ( 
a<over>(x<plus>y<superscript> (3) ) 
) 

<EQUALS> <SQRT>(<times><pi>) 
<ENDMATH> 


This example illustrates how to use the <GROUP> tag to indicate the order 
of operation. Its output is: 
a 
= V kT 


t+y 





Note what the output would be if the <GROUP> tag is not present: 
a 
r+yo = Ser 
<MATH> (total = A+B-C¥*D/ &) 


In this example, the characters representing the mathematical operations are 
used directly. The output is: total = A+ B—C* D/E. Note that this is 
equivalent to: 


<MATH> (total <EQUALS> A <PLUS> B <MINUS> C <TIMES> D <DIVIDED_BY> E) 
<MATH>(--)This begins a comment line. 


This example illustrates how to use the <MATH> tag to generate true minus 
signs in your SDML files. This example results in: 


——This begins a comment line. 


<math> 

widgets = crickets + bats 
<ENDMATH> 

<p>As <reference>(widgets) shows... 


This example may produce an example like: 


widgets = crickets + bats 


As (1-3) shows... 
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<MATH_CHAR> 


Creates a special mathematical symbol. 





FORMAT 


<MATH_CHAR> (keyword) 





ARGUMENTS 


related tags 


restrictions | 


required 
terminator 


keyword 
A keyword indicating the special symbol you want to access. The keywords, 
and the symbols they produce, are listed in Table 9-5. 





e <MATH> —provides tags for operations in constructing mathematical 
expressions. 


¢ | <MCS>—provides access to special characters available in the DEC 
Multinational Character Set. 


bd <SPECIAL_CHAR> 





¢ The <MATH—CHAR> tag is invalid in the monospaced example tags. 


The characters produced using <MATH—CHAR> are sized only for normal 
text sizes and therefore will not produce good visual results in header 
levels, text in the OVERHEADS doctype, and so on. 





None. 


DESCRIPTION Table 9-5 summarizes the keywords and special symbols you can access with 
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the <MATH_CHAR> tag. 


Table 9-5 <MATH_CHAR> Symbols 


Keyword Symbol 
The Greek Letters 
ALPHA 

BETA 

GAMMA 

DELTA 

EPSILON 
VAREPSILON 
ZETA 

ETA 

THETA 


~n M2 DW OQ 


Qo 3g: Sm Mm 


Table 9—5 (Cont.) <MATH_CHAR> Symbols 


Keyword 
The Greek Letters 


VARTHETA 
lOTA 
KAPPA 
LAMBDA 
MU 

NU 

XI 
OMICRON 
PI 

VARPI 
RHO 
VARRHO 
SIGMA 
VARSIGMA 
TAU 
UPSILON 
PHI 
VARPHI 
CHI 

PSI 
OMEGA 


The Uppercase Greek Letters 
UPPERCASE_ALPHA 
UPPERCASE_BETA 
UPPERCASE_GAMMA 
UPPERCASE_DELTA 
UPPERCASE_EPSILON 
UPPERCASE_ZETA 
UPPERCASE_ETA 
UPPERCASE_THETA 
UPPERCASE_IOTA 
UPPERCASE_KAPPA 
UPPERCASE_LAMBDA 
UPPERCASE_MU 
UPPERCASE_NU 
UPPERCASE _ XI 


Symbol 


~ 


oO mM et Rp Me B 


77 Go RB PB gq A 


gc €& xk 6 GS C 


Nn 2eenNromnNweepn woe 


<MATH_—CHAR> 


9-151 


<MATH_CHAR> 


Table 9—5 (Cont.) <MATH_CHAR> Symbols 


Keyword Symbol 
The Uppercase Greek Letters 
UPPERCASE_OMICRON 
UPPERCASE _PI 
UPPERCASE_RHO 
UPPERCASE_SIGMA 
UPPERCASE_TAU 
UPPERCASE _UPSILON 
UPPERCASE _PHI 
UPPERCASE_CHI 
UPPERCASE_PSI 
UPPERCASE_OMEGA 


5 e@*« @R HM UVHO 


The Ordinal Operators 
ALEPH 

ANGLE 
BACKSLASH 
BOT 
CLUBSUIT 
DIAMONDSUIT 
DOUBLE_VERT 
ELL 
EMPTYSET 
EXISTS 

FLAT 

FORALL 

HBAR 
HEARTSUIT 
IMATH 

IM 

INFTY 

JMATH 
NABLA 
NATURAL 

NEG 

PARTIAL 
PRIME 

RE 

SHARP 


> @ EON 


mat gotgu<rues= 


J 


32 ~ & 


—_ 
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Table 9—5 (Cont.) 


Keyword 

The Ordinal Operators 
SPADESUIT 

SURD 

TOP 

TRIANGLE 

wpe 


Binary Operators 
AMALG 

AST 

BIGCIRC 
BIGTRIANGLEDOWN 
BIGTRIANGLEUP 
BULLET 

CAP 

CDOT 

CIRC 

CUP 

DAGGER 
DDAGGER 
DIAMOND 

DIV 

MP 

ODOT 

OMINUS 

OPLUS 

OSLASH 
OTIMES — 


<MATH_CHAR> Symbols 


Symbol 


Ss PAX ® 


E 


o> rey 


> 


° 


oO + +— C 


® © @ O © H 


<MATH_CHAR> 
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Table 9—5 (Cont.) <MATH_CHAR> Symbols 


Keyword Symbol 
Binary Operators 


PM 

SETMINUS 
SQCAP 

SQCUP 

STAR 

TIMES 
TRIANGLELEFT 
TRIANGLERIGHT 
UPLUS 

VEE 

WEDGE 

WR 


GV Ase. a ae 


~ >< 
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Table 9—5 (Cont.) 


Keyword 
Relational Operators 
APPROX 
ASYMP 
BOWTIE 
CONG 

DASHV 
DOTEQ 

EQUIV 
FROWN 

GEQ 

GG 

IN 

LEQ 

MID 

MODELS 

NI 
NOTSUBSETEQ 
NOT_APPROX 
NOT_ASYMP 
NOT_CONG 
NOT_EQUIV 
NOT_EQ 
NOT_GEQ 
NOT_GT 


<MATH_CHAR> Symbols 


Symbol 


ly —L I Xx 


viv) ill 


MM KH HOR KH RM VT IA Am 


<MATH_CHAR> 
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<MATH_CHAR> 


Table 9—5 (Cont.) <MATH_CHAR> Symbols 


Keyword Symbol 
Relational Operators 


NOT_LEQ 
NOT_LT 
NOT_PRECEQ 
NOT_PREC 
NOT_SIMEQ 
NOT_SIM 
NOT_SOSUBSETEO 
NOT_SOSUPSETEQ 
NOT_SUBSET 
NOT_SUCCEQ 
NOT_SUCC 
NOT_SUPSETEO 
NOT_SUPSET 
PARALLEL 
PERP 
PRECEQ 
PREC 
PROPTO 
SIMEQ 
SIM 
SMILE 
SQSUBSETEQ 
SQSUPSETEO 
SUBSETEQ 
SUBSET 
SUCCEQ 
SUCC 
SUPSETEQ 
SUPSET 
~ VDASH 


bby KRW MN RRARANM 


Ro AIK. 


I 


2 


TU YY A IN wd ( 
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<MATH_CHAR> 


Table 9—5 (Cont.) <MATH_CHAR> Symbols 


Keyword Symbol 
Arrows 
DOUBLE_DOWNARROW 
DOUBLE _LEFTARROW 
DOUBLE _LEFTRIGHT ARROW 
DOUBLE LONGLEFT ARROW 
DOUBLE —LONGLEFTRIGHT ARROW 
DOUBLE_LONGRIGHT ARROW 
DOUBLE _RIGHT ARROW 
DOUBLE_UPARROW 
DOUBLE_UPDOWNARROW 
DOWNARROW 

HOOKLEFT ARROW 
HOOKRIGHT ARROW 

LEFT ARROW 
LEFTHARPOONDOWN 
LEFTHARPOONUP 
LEFTRIGHT ARROW 
LONGLEFTARROW 
LONGLEFTRIGHT ARROW 
LONGMAPSTO 

LONGRIGHT ARROW 
MAPSTO 

NEARROW 

NW ARROW 

RIGHT ARROW 
RIGHTHARPOONDOWN 
RIGHTHARPOONUP 
RIGHTLEFTHARPOONS 
SEARROW 

SW ARROW 

UPARROW 
UPDOWNARROW 


ees Nee Ae WP iW ew Not i[ sD Toe hed Da cde Tees ee if et 
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<MATH_CHAR> 
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Table 9—5 (Cont.) <MATH_CHAR> Symbols 


Keyword Symbol 
Delimiters 
LANGLE 
RANGLE 
LBRACE 
RBRACE 
LBRACK 
RBRACK 
LCEIL 
RCEIL 
LFLOOR 
RFLOOR 


— Oe 


e_- -— —— == 


<MCS> 





<MCS> 


Labels a character in the DEC Multinational Character Set. 








FORMAT <MCS> (character) 

ARGUMENTS character 
Specifies the character referred to. The character may be any one of the 
following: 
Argument Character Decimal Value 
spanish_inverted_exclamation i 161 
cents ¢ 162 
british_pound £ 163 
— [reserved] 164 
japanese_yen ¥ 165 
— [reserved] 166 
section_sign § 167 
general_currency a] 168 
copyright © 169 
feminine_ordinal a 170 
double_open—angle_brackets « 171 
— [reserved] 172 
— [reserved] 173 
— [reserved] 174 
—_— [reserved] 175 
degree ° 176 
plus_or_minus of 177 
superscript2 2 178 
superscript3 3 179 
— [reserved] 180 
micro m 181 
pilcrow q 182 
raised_period . 183 
— [reserved] 184 
superscript 1 ‘ 185 
masculine_ordinal Q 186 
double_close_angle_brackets » 187 
one_fourth % 188 
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<MCS> 


9-160 


Argument 


one_half 


spanish_inverted_question 


cap_a_grave 
cap_a_acute 
cap_a_circumflex 
cap_a_tilde 
cap__a_umlaut 
cap_a_ring 
cap_ae 
cap_c_cedilla 
cap_e_grave 
cap__e_acute 
cap__e_circumflex 
cap__e_umlaut 
cap_i_grave 
cap_i_acute 
cap_i_circumflex 
cap_i_umlaut 
cap_n_tilde 
cap_o_grave 
cap__o_acute 
cap_o_circumflex 
cap_o_tilde 
cap_o_umlaut 
cap_oe 
cap_o_slash 
cap_u_grave 
cap_u_—acute 
cap_u__circumflex 
cap_u_umlaut 
cap_y_umilaut 
german_ss 
small_a_grave 
smail_a_acute 
smail_a_circumflex 
small_a_tilde 


a a mm: m™ mr TT 6 mA yo >: >: > >. > ios 


Character 
vA 


[reserved] 


[reserved] 


<cOoCcCARM OOOO Oo 2 


[reserved] 


o a DW 


o> 


az 


Decimal Value 


189 
190 
191 
192 
193 
194 
195 
196 
197 
198 
199 
200 
201 
202 
203 
204 
205 
206 
207 
208 
209 
210 
211 
212 
213 
214 
215 
216 
217 
218 
219 
220 
221 
222 
223 
224 
225 
226 
227 


related tags 


restrictions 


required 
terminator 








<MCS> 


Argument Character Decimal Value 
small_—_a_umlaut a 228 
small_a_ring a 229 
small_ae ee 230 
small_c_cedilla g 231 
small_e_grave e 232 
small_e_acute é 233 
small_e_circumflex é 234 
small_e_umlaut é 235 
small_i_grave i 236 
small_i_acute i 237 
small_i_circumflex i 238 
small_i_umlaut 7 239 
— [reserved] 240 
small_n_tilde n 241 
small_o_grave fo) 242 
small_o_acute 6 243 
small_o_circumflex re) 244 
small_o_tilde 6 245 
small_o_umlaut 6 246 
small_oe ce 247 
small_o_slash @ 248 
small_u_—agrave u 249 
small_u_acute ui 250 
small_u_circumflex T 251 
small_u_—umlaut u 252 
small__y_umlaut y 253 
— [reserved] 254 





e <MATH—CHAR> 


bd <SPECIAL__CHAR> 





Invalid in math. 





None. 


DESCRIPTION The <Mcs> tag labels a character in the DEC Multinational Character Set. 
Note that this tag is required only when the input device (terminal) you are 
using does not accept or display these special characters. 


<MCS> 





EXAMPLE 


<P>The DEC Multinational Character Set includes the currency sign 
for the Japanese yen (<MCS>(japanese_yen)). 


This example may produce the following output: 


The DEC Multinational Character Set includes the currency sign for the 
Japanese yen (¥). 
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<NESTED_TABLE_BREAK> 


<NESTED_TABLE_BREAK> 


Marks a place that a nested table may be broken across pages. 





FORMAT <NESTED_TABLE_BREAK> 


ARGUMENTS = None. 








related tags °  <TABLE> 
<TABLE_FILE> 


<TABLE_SPACE> 


<REFERENCE> 





restrictions Must be used within a table. Also, breakpoints for long tables nested inside 
multipage tables have the following limitations: 


e = The first level table must not use the KEEP attribute. 


¢ The first level table must be set up with only two or three columns. 





required None. 
terminator 





DESCRIPTION The <NESTED_TABLE_BREAK> tag marks a place that a nested table may be 
broken across pages. 


If you place a <NESTED_TABLE_BREAK> tag in a nested table which contains 
headings, the headings are not repeated on subsequent pages. Also, a rule 
may be output at the point that the tag is included, appearing to end the 
nested table, although the nested table continues past the rule. 


EXAMPLE 


<TABLE>(Table Caption\tab_log_name) 
<TABLE_SETUP>(2\10) 

<TABLE_HEADS>(First Head\Second Head) 
<TABLE_ROW>(Item Here\Definition for Item here.) 
<TABLE_ROW>(Item Here\Definition for Item here.) 
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<NESTED_TABLE_BREAK> 


<TABLE> 

<TABLE_SETUP>(2\15) 

<TABLE_ROW>(Item\Text of item description here) 
<TABLE_ROW>(Item\Text of item description here) 


<TABLE_ROW>(Item\Text of item description here) 
<TABLE_ROW>(Item\Text of item description here) 
<NESTED_TABLE_BREAK> 

<TABLE_ROW>(Item\Text of item description here) 


<TABLE_ROW>(Item\Text of item description here) 
<NESTED_TABLE_BREAK> 
<TABLE_ROW>(Item\Text of item description here) 


<TABLE_ROW>(Item\Text of item description here) 


<TABLE_ROW>(Item Here\Definition for Item here.) 
<TABLE_ROW>(Item Here\Definition for Item here.) 


<ENDTABLE> 


This example illustrates the coding of the <NESTED_TABLE_BREAK> tag. 
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<NEWTERM> 


<NEWTERM> 


Labels a term first introduced into the text in order to emphasize the term. 





FORMAT = = <NEWTERM> (term) 


Hy 


ARGUMENTS'- term 


‘ Specifies the word just introduced. 








related tags ¢  <KEYWORD> 
. <VARIABLE> 








restrictions Invalid in math. 
required None. 
terminator 


DESCRIPTION The <NEWTERM> tag labels a term first introduced into the text in order to 
emphasize the term. In output, the term will be italicized. 





EXAMPLE 


<P>To begin a session at the terminal, you must first <NEWTERM>(log in). 
Logging in consists of getting the system’s attention and identifying yourself as 
an authorized user. 


This example may produce the following output: 


To begin a session at the terminal, you must first log in. Logging in consists. 
of getting the system’s attention and identifying yourself as an authorized 
user. 
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<NOTE> 


<NOTE> 


Labels a note, caution, warning, or some other portion of text to which 
you wish to draw attention. 





FORMAT <NOTE> [(heading-text)] 
note-text 


<ENDNOTE> 





ARGUMENTS _heading-text 


Specifies text for a heading other than the default heading “Note:.” 











note-text | 
Specifies the text of the note. A paragraph is implied here, so no <P> tag is 
needed. 

related tags None. 

restrictions None. 

required <ENDNOTE> 


terminator 





DESCRIPTION The <NOTE> tag labels a note, caution, warning, or some other portion of 
text to which you wish to draw attention. A note will be formatted differently 
depending on the doctype specified on the DOCUMENT command line. 


EXAMPLE 


<NOTE>(Caution) You should abort the system generation command 
procedure only after Phase 1 has completed processing. 
<ENDNOTE> 


This example might produce the following output, depending on the doctype 
specified: | 


Caution: You should abort the system generation command procedure only after 
Phase 1 has completed processing. 
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<OPAREN> 


<OPAREN> 


Supplies an unmatched opening parenthesis in an argument to a tag. 





FORMAT 


<OPAREN> 





ARGUMENTS 


related tags 


None. 





e The following tags label other characters that must be tagged when they 
occur in an argument to a global tag: 


<AMPERSAND> 
<BACKSLASH> 
<CPAREN> 
<VBAR> 














restrictions None. 

required None. 

terminator 

DESCRIPTION The <OPAREN> tag can be used anywhere to insert an open parenthesis 
character into text. However, it is only beneficial (in terms of keystrokes and 
control of the output) as an unmatched opening parenthesis in an argument 
passed to a tag. 
An unmatched parenthesis in an argument can cause errors when processed 
because the parentheses are used to determine the beginning and ending 
of an argument list. The <OPAREN> tag inserts the opened parenthesis 
character but is not evaluated as an opened parenthesis. 

EXAMPLE 


<SUBHEAD1>(Using an Opened Parenthesis <PARENDCHAR>(<OPAREN>) in an Argument to a Tag) 


This example may produce the following output: 


Using an Opened Parenthesis (() in an Argument to a Tag 
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<ORDER_NUMBER> 


<ORDER_NUMBER> 


Labels the order number or part number that may appear on the title page 
of a book. 





FORMAT <ORDER—_NUMBER> (number) 





ARGUMENTS number 


Specifies the order number for the book. 











related tags None. 

restrictions The <ORDER-NUMBER> tag is valid only within a title page. 
required None. 

terminator 





DESCRIPTION The <ORDER-NUMBER> tag labels the order number or part number that may 
appear on the title page of a book. 





EXAMPLE See the example in the <FRONT_MATTER> discussion. 
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<P> 


Marks the beginning of a new paragraph. 











FORMAT <P> 

ARGUMENTS = None. 

related tags ° <cP> 
e <LINE> 


restrictions 


required 
terminator 


e <CENTER_LINE> 


° <RIGHT_LINE> 





None. 





None. 





DESCRIPTION 


The <P> tag marks a new paragraph of text. An internal counter keeps track 
of the context in which the new paragraph begins, so that you can freely use 
<P> tags inside lists and in other contexts where you want to start a new 
paragraph, while maintaining the same logical level of discussion. 


A <P> tag is expected after every heading. If you do not immediately start a 
new paragraph after a heading, you must label the beginning of another text 
element, such as a list. 





EXAMPLES 


<P> 


Here is a sentence or two in a paragraph. The following paragraph 
will show the <TAG>(P) tag at work separating paragraphs. 
<P>Here is the second paragraph so that you can observe the relationship 


it has to the first. 


This example may produce the following output, depending on the doctype 
specified: 


Here is a sentence or two in a paragraph. The following paragraph will show 
the <P> tag at work separating paragraphs. 


Here is the second paragraph so that you can observe the relationship it has 
to the first. 
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<P> 


2 <list> (unnumbered) 
<le>Oranges 
<le>Apples 
<p>Note that there are several types of apples<hellipsis> 
<le>Bananas 
<endlist> 


This example shows how a paragraph can be used within a list. This example 
may produce the following output: 
e Oranges 
e Apples 
Note that there are several types of apples ... 


e Bananas 
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<PAGE> 


<PAGE> 


Breaks a page of text, forcing the text that follows the tag to begin on a 
new page. 








FORMAT EVEN 
<PAGE> 
3 lt ODD } 
ARGUMENTS EVEN 
ODD 


related tags 


restrictions 


required 
terminator 


Specifies whether the new page of output should have an even or an odd 
page number. 


Note that if you use one of these arguments, you might have two consecutive 
pages of output numbered such as 13 or 15. There will be no blank page of 
output between the pages. 





e <FINAL_CLEANUP> —page—break 





The arguments EVEN and ODD are invalid in tables. 


Invalid in math. 





None. 


DESCRIPTION The <PacE> tag breaks a page of text, forcing the text that follows the tag to 


begin on a new page. 


Note: Use this tag only in special cases, where a page must be broken at that 


point. This tag is not for general use, such as for overall pagination; 
this can jeopardize the output format and device independence of your 
generically coded source file. 
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<PAGE> 





EXAMPLE 


<HEAD1>(Survey Results) 


<PAGE> 
<HEAD2>(Brand X) 


<PAGE> 
<HEAD2> (Brand Z) 


This example shows the coding of a short document in which the information 
might be easier to index when specific headings start on new pages. 
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<PARENDCHAR> 


<PARENDCHAR> 


Labels a character that will appear alone within parentheses to achieve 
better spacing. 





FORMAT 


<PARENDCHAR > (char) 





ARGUMENTS 


telated tags 
restrictions 


required 
terminator 


char 
Specifies the character within parentheses. Specify only the character. The 
parentheses will be added during processing. 





None. 





Invalid in math. 





None. 


DESCRIPTION 


Frequently writers use the name for a special character followed by that 
character in parentheses. For instance, in discussing wildcard characters it is 
natural to say, “The percent sign (% ) is the wildcard for a single character.” 


A problem in using proportionally spaced fonts is that single characters 
surrounded by parentheses can look quite crowded, like this: “The percent 
sign (%) is the wildcard for a single character.” (Compare the percent sign 
in parentheses i in this paragraph to the percent sign in parentheses in the 
previous paragraph; you can see the slight crowding at the top left corner of 
the percent sign.) 


Typographers put a small amount of space, called a “thin space,” between the 
parentheses and the single character to achieve a balance. When you use the 
<PARENDCHAR> tag, that thin space is added for you. 


You should use the <PARENDCHAR> tag to label characters that are small or 
that are more vertical than horizontal in shape. 


When using the <PARENDCHAR> tag, do not enter the parentheses that will 
surround the character. The parentheses will be added during processing. 
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<PARENDCHAR> 





EXAMPLE 


<P>The tilde <PARENDCHAR>(~) is used to prevent the word 
following it from becoming a main entry in the index. 


This example may produce the following output: 


The tilde (~ ) is used to prevent the word following it from becoming a main 
entry in the index. . 


Without the <PARENDCHAR> tag, your output would look like this: 


The tilde (~) is used to prevent the word following it from becoming a main 
entry in the index. 
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<PART> 


<PART> 


Labels the start of a major division within a document, and starts it on a 
new page. 





FORMAT 


<PART > /(zone-title \ symbol-name)] 














ARGUMENTS zone-title 
oe ae Specifies the title for this part of your document. 

symbol-name 
Specifies the term that you assign to this part and then use to reference the 
part throughout your document. The symbol-name argument is required only 
if the part will be included in a bookbuild. 
Symbol-names must not exceed 31 characters, and must only contain 
alphabetic letters, numbers, or underscores in them. Do not begin a symbol- 
name with an underscore. 

restrictions None. 

required None. 

terminator 

DESCRIPTION A document may be logically divided into units called “Parts,” which may 


consist of the following: 
e A set of chapters or appendixes whose contents are logically related. 


e A collection of units of logically related information, for example, 
reference items in the SOFTWARE doctype. 


The <PART> tag begins a new part and optionally assigns a title to it. Like 
chapters, parts are automatically numbered. If you specify a symbol-name 
argument, a symbol table entry is created for the part. 


The <PART_PAGE> tag creates a divider page for a part and optionally 
provides an abstract describing information in the part. 


By default, the part page is assigned the next odd page number in the 
current numbering sequence in a document that does not have chapters. 
If RENUMBER is specified in the <ENDPART_PAGE> tag, the part page 
is assigned the page number of 1, and the next printed page of output is 
numbered page 3. 


<PART> 





EXAMPLES 


4] <part>(Reference Information\ref_part) 
<part_page> 
<title>(<reference>(ref_part) \<reference>(ref_part\text) ) 
<abstract> 
This part contains reference chapters. <reference>(intro_part) 
contains tutorial information. 
<endabstract> 
<endpart_page> 


This example shows how to code the tags <PART> and <PART_PAGE>, 
assigning a zone-title and a symbol-name to a part. 


2 <part>(Introduction\intro_part) 
<part_page> 
<title>(<reference>(intro_part) \<reference>(intro_part\text) ) 
<abstract> 
This part contains introductory chapters. <reference>(ref_part) 
contains more detailed reference information. 
<endabstract> 
<endpart_page> 


This example results in the following if this is the first part specified in the 
document. 


e A symbol table entry for the symbol-name intro_part, whose value is 1 
and whose text is “Introduction.” 


e The <PART_PAGE> tag creates a new page of output. The page is 
assigned the next odd page number in the numbering sequence. 


¢ The title: “PART I Introduction” will be printed at the top of the page. 
The use of uppercase roman numerals to display the part number is a 
document-type-specific design attribute. 


e The abstract text is printed. 
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<PART_PAGE> 





<PART_PAGE> 


Begins a divider page for a new part of a document. 





FORMAT <PART_PAGE> 





ARGUMENTS = None. 





related tags °  <TITLE> 
©  <RUNNING_TITLE> 


° <ABSTRACT> 








restrictions None. 
required <ENDPART_PAGE> 
terminator 





DESCRIPTION The <PartT> tag divides a document into one of its major constituent parts. 
The <PART_PAGE> tag (together with <ENDPART_PAGE> ) simply inserts an 
extra page in between major sections. 


By labeling a part page, you also define three related tags: <TITLE>, 
<ABSTRACT> , and <RUNNING_TITLE>. You can use these related tags to 
put either a title or an abstract on the page (or both), and you can determine 
the running title for the text that follows the part page as well. 





EXAMPLE 


<PART_PAGE> 

<TITLE>(Part II) 

<ABSTRACT> 

Part II provides reference information on each global tag in SDML. 
<ENDABSTRACT> 

<RUNNING_TITLE>(Descriptions of Global Tags) 

<ENDPART_PAGE> 


This example illustrates the use of both the <PART_PAGE> and <ENDPART_ 
PAGE> tags, and the related tags that can be used to put a title on the page, 
print a brief abstract, and set the running title for the text that follows. 
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<PREFACE> 


<PREFACE> 


Labels the beginning of a preface. 





FORMAT 


<PREFACE> |[(page-number)] 





ARGUMENTS 


related tags 
restrictions 


required 
terminator 


page-number 

Specifies the page number on which you wish the preface to begin. You must 
specify the number with an Arabic numeral (the number in the formatted 
result will be a lowercase Roman numeral). If you do not specify a number, 
the default page on which to begin the preface is Roman numeral five. 


The page-number can be either a positive or negative value. 





None. 





This tag must be used in the context of a <FRONT_MATTER> tag. 





<ENDPREFACE> 


DESCRIPTION 


If the preface of a document is placed after the table of contents, you must 
specify the starting page number for the preface. You cannot know what this 
number will be until the document is nearly completed and you know what 
the page count is for the table of contents. 


The table of contents file usually begins on page 3, which is normally output 
as iii, When you have examined the table of contents output, you then can 
know the table of contents’ last page. Specify the next odd number to set the 
correct page number for the preface. 





EXAMPLE 
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See the example in the discussion of the <FRONT_MATTER> tag. 


<PREFACE_SECTION> 


<PREFACE_SECTION> 


Creates a major section in the preface of a book to provide information 
such as a summary of changes to the book. 





FORMAT <PREFACE_SECTION> (title) 





ARGUMENTS title 


Specifies the title given to this preface section. 











related tags = ° <PREFACE> 

restrictions The <PREFACE_SECTION> tag is valid only within the front matter. 
required None. 

terminator 





DESCRIPTION The <PREFACE-SECTION> tag creates a major section in the preface of a book 
to provide information such as a summary of changes to the book. 





EXAMPLE See the example in the discussion of the <FRONT_MATTER> tag. 
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<PRINT_DATE> 


<PRINT_DATE> 


Inserts a print date line on the copyright page. 





FORMAT <PRINT_DATE> (date) 





ARGUMENTS date 


Specifies official printing date information for the book. 





related tags None. 





restrictions The <PRINT_DATE> tag is valid only within a copyright page, within 
<FRONT_MATTER> and <ENDFRONT_MATTER> . 





required None. 
terminator 





DESCRIPTION The <PRINT_DATE> inserts a print date line on the copyright page. 





EXAMPLE See the example in the <FRONT_MATTER> tag. 
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<PROFILE> 


<PROFILE> 


Indicates that the source file is a profile and that a bookbuild is to be 
performed. 





FORMAT 


<PROFILE> 





ARGUMENTS 


related tags 


None. 





bd <ELEMENT> 


° <INCLUDES_FILE> 











restrictions None. 

required <ENDPROFILE> 

terminator . ; 

DESCRIPTION A profile of a book is required in order to build (process) a book. A book’s 


profile begins with a <PROFILE> tag and ends with the <ENDPROFILE> tag. 
Between the <PROFILE> and <ENDPROFILE> tags, each element of the book 
is introduced with an <ELEMENT> tag. 


Only those files listed with <ELEMENT> tags are included in the book during 
the bookbuild. They should be listed in the profile in the order in which they 
are presented in the book. 


Within a profile file, never include a tag that contains text. Also, do not place 
an <INCLUDE> tag in a profile. 


There are several optional tags that can be included between the <PROFILE> 


and <ENDPROFILE> tags, other than <ELEMENT> tags. These include the 
following: 


<INDEX _FILE> 


<CONDITION> and <ENDCONDITION> 


<CONTENTS_FILE> 


<COMMENT> and <ENDCOMMENT> 


<INCLUDES_FILE > 


See Chapter 4 for more information on book building. 
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<PROFILE> 





EXAMPLE 


<REFERENCE> (PROFILE) 

<ELEMENT> (Front_material .SDML) 
<ELEMENT> (Sales . SDML) 
<ELEMENT> (Accounting . SDML) 
<ELEMENT> (Marketing . SDML) 
<ELEMENT> (Communication. SDML) 
<ELEMENT> (Appendix. SDML) 
<endprofile> 


This example illustrates the profile of a book that contains front-matter, four 
chapters, and an appendix. The profile shown in this example must be in a 
file by itself. The file might be called by a name that indicates it is a profile, 
such as “COMPANY_PRO.SDML.” 


Each of the files named in the <ELEMENT> tags should begin with one of the 
book element tags, such as <CHAPTER> (Sales This Year\sales_chap). 
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<QUOTE> 


<QUOTE> 


Labels quoted material in the output. 








FORMAT <QUOTE> (quote-text) 
or 
<QUOTE> 
quote-text 
<ENDQUOTE> 
ARGUMENTS quote-text 


related tags 


Specifies the quoted text. 





¢ The following tags are used to label single occurrences of a quotation 
mark: 


<DOUBLE_QUOTE> 
<SINGLE_QUOTE> 











restrictions None. 

required <ENDQUOTE> —Required if the text is not passed as an argument. 
terminator 

DESCRIPTION The reason for the <QUOTE> tag lies in a mismatch between conventions 


used in the typesetting world and conventions used in the computing world. 
Your terminal keyboard has two possible characters you can use for quotation 
marks: the " (SPACE) (ASCII 34) and the ' (SPACE) (ASCII 39). Neither 
distinguishes between open quotation marks and close quotation marks. You 
use the same character twice to enclose a word in quotation marks: 


"a quoted string” 


Typesetters, on the other hand, scrupulously distinguish between open 
quotation marks and closed quotation marks. The former look like small 
sixes; the latter, like small nines. Look carefully at a typeset document and 
you will immediately see the difference between open and close quotation 
marks. 
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<QUOTE> 





EXAMPLES 


In order to obtain the proper quotation marks in your typeset output, you 
must label material inside quotation marks with the <QUOTE> tag. If you 
use the keyboard quote character instead of the <QUOTE> tag, the open and 
close quotes in your typeset document will both look like small, double nines. 
If you use the tag, your output will contain the proper opening and closing 
quotation marks for the font in which your text is set. 


[J <P>The symbol B will be defined to be the string <QUOTE> (April 


showers) . 


This example may produce the following output: 
The symbol B will be defined to be the string “April showers.” 


Note the placement of the period at the end of the sentence. If you want 
a punctuation mark enclosed outside the quotes, you must not make the 
punctuation mark part of the argument to the <QUOTE> tag. 


2 <P>Abraham Lincoln once wrote, <QUOTE> I claim not to have controlled 
events, but confess plainly that events have controlled me. <ENDQUOTE> 


9-184 


This example may produce the following output: 


Abraham Lincoln once wrote, “ I claim not to have controlled events, but 
confess plainly that events have controlled me. ” 


<REFERENCE> 





<REFERENCE> 


Makes a reference to a symbol-name in a book element or text element. 
When processed, <REFERENCE> is replaced with the current value of the 
symbol-name. 





FORMAT 


<REFERENCE> (symbol-name[ \ keyword]) 





ARGUMENTS 


related tags 
restrictions 


required 
terminator 


symbol-name 
Specifies the name of a symbol assigned in a book element or text element 
tag (for example, <HEADx> or <TABLE> ). 


Make sure that the symbol-names, that you define in the book element or 
text element tags, do not exceed 31 characters, and only contain alphabetic 
letters, numbers, or underscores in them. Do not begin a symbol-name with 
an underscore. 


keyword | 
Specifies an optional keyword indicating the type of text replacement to occur 
in conjunction with the reference: 


Keyword Reference Output 


null Outputs the current value of the symbol and its related 
symbol type text, for example “Figure 3-2.” This is the 
default. 

VALUE Outputs only the current value of the symbol, for example, 


the heading level number or the table number, without any 
related text. 


TEXT Outputs only the text associated with the symbol table 
entry, that is, the caption (for figures, tables, and 
examples), or the heading-text (for chapter, section 
and heading-level tags). 


FULL. Outputs all information associated with the symbol, 
including the value, type, and text. 





None. 





None. 





<REFERENCE> 





DESCRIPTION This tag refers to a symbol-name that is specified as an argument in a text or 
book element. When processed, the <REFERENCE> tag is replaced with the 
current value of the symbol-name that is stored in the cross-reference file. 


A second argument to the tag controls the exact output of the reference. 
When you do not specify a second argument, the output defaults according to 
the symbol-type. Table 9-6 summarizes the default output for each type of 


text or book element. 


Table 9-6 Element Types and Default Output of Symbol-Names | 


Second Argument to <REFERENCE> 


Text Element (null) VALUE TEXT 

BOOK TITLE The title argument specified in <DEFINE_BOOK_NAME> . 
EXAMPLE Example number number Caption argument 
FIGURE Figure number number Caption argument 
HEADx Heading number number Caption argument 
TABLE Table number number Caption argument 
TEXT STRING The text-string argument specified in <DEFINE_SYMBOL> . 
Book Elements (null) VALUE TEXT 

APPENDIX Appendix letter letter Title argument 
CHAPTER Chapter number number Title argument 
-FRONT MATTER None None None 

GLOSSARY None None None 

PART Part number number Title argument 


FULL 


Example number, 
Caption argument 


Figure number, Caption 
argument 


Heading number, 
Caption argument 


Table number, Caption 
argument 


FULL 


Appendix letter, Title 
argument 


Chapter number, Title 
argument 


None 
None 


Part number, Title 
argument 


See Chapter 6 for more information on symbol-names and cross-referencing. 





EXAMPLES 


<REFERENCE>(lognames_tab) shows ten default system logical names. 
<TABLE>(system logical name\lognames_tab) 


This example shows the use of <REFERENCE> and <TABLE> to reference the 
symbol-name of a table. As shown, the symbol-name “lognames_tab” was 
defined in <TABLE> and then referenced with the <REFERENCE> tag. This 


example has the following output: 


Table 1-4 shows ten default system logical names. 
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<REFERENCE> 


<P>See Chapters <REFERENCE>(lognames_chap\VALUE) and 
<REFERENCE>(filespec_chap\VALUE) to see 


This example shows the use of the tag <REFERENCE> to make a chapter 
number reference without outputting any related information, such as the 
chapter title. This example has the following output: 


See Chapters 3 and 4 to see... 
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-<REVISION> 


<REVISION> 


Indicates that the document contains either new or modified information 
and enables the output of the <MARK> tag. 





FORMAT 


<REVISION> [(UPDATE | \ update-info])] 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


UPDATE 

Must be specified if the document is being produced for an update. If 
you specify UPDATE, the file must contain the <UPDATE_RANGE> and 
<ENDUPDATE_RANGE> tags to indicate the pages to be processed. If no 
<UPDATE_RANGE> tags are present, no output will be produced. 


update-info 

Specifies information that is related to the system version and the date of the 
update. If specified, this text appears on the bottom of each page of output in 
the update. 





. <MARK> 


. <UPDATE_RANGE> 





None. 





None. 


DESCRIPTION The <REVISION> tag can be used in any document type for which you want 
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to indicate to reviewers new or changed information. 


This tag enables the <MARK>, <ENDMARK>, <UPDATE-RANGE> , and 
<ENDUPDATE_RANGE> tags. By default, these tags are defined for all 
document types to be non-operational; thus, if a file is processed without 
the <REVISION> tag, they produce no output. 


When a file that contains the <REVISION> (UPDATE) tag is processed, the table 
of contents and index are handled as follows: 


If the <CONTENTS_FILE> or <INDEX_FILE> tag occurs between 

the bounds of <UPDATE_RANGE> and <ENDUPDATE_RANGE>, and _ 
/CONTENTS or /INDEX is specified on the command line, the contents 
file or index file is included within the pages for the update range. 


If the <CONTENTS_FILE> or <INDEX_FILE> tag occurs in the file but is 
specified outside the bounds of <UPDATE_RANGE> and <ENDUPDATE_ 
RANGE> tags, and if /CONTENTS or /INDEX is specified on the 
command line, the table of contents file or index file is included in 
the output file. 


<REVISION> 





EXAMPLES 


2 


<DOCTYPE> (SOFTWARE) 
<REVISION> 


<P> 

The following characters are legal in MACRO-11 source programs: 
<LIST> (NUMBERED) 

<LE>The letters A through Z. Both upper- and lowercase letters are 
acceptable, although, upon input, lowercase letters are converted to 
uppercase. 

<MARK> 

<LE>Characters in the DEC multinational character set (MCS). A chart 
showing the MCS is located in <REFERENCE>(mcs_app) , 

with a list of directives that support the MCS. 

<LE>The digits 0 through 9. 

<ENDMARK> 

<LE>The characters period <PARENDCHAR>(.) and dollar sign 
<PARENDCHAR>($). These characters are reserved for use as Digital 
Equipment Corporation system program symbols. 

<ENDLIST> 


This example shows the use of the <REVISION> tag in a document that is 
extensively revised. The formatted output may be as follows: 


The following characters are legal in MACRO-11 source programs: 


1 The letters A through Z. Both upper- and lowercase letters are acceptable, 
although, upon input, lowercase letters are converted to uppercase. 


2 Characters in the DEC multinational character set (MCS). A chart showing 
the MCS is located in Appendix A, with a list of directives that support 
the MCS. 


3 The digits 0 through 9. 


4 The characters period (.) and dollar sign ($). These characters are 
reserved for use as Digital Equipment Corporation system program 
symbols. 


<REVISION>(UPDATE\July 1986) 


<UPDATE_RANGE>(3\10) 


This example shows the use of the <REVISION> tag in a manual that was 
updated in July of 1986. See the <UPDATE_RANGE> tag for more information 
on identifying a section of updated material. 
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<REVISION_INFO> 


<REVISION_INFO> 


Labels a section on a title page that provides information on what previous 
books have been superseded by the current one. 





FORMAT 


<REVISION_INFO> ([title-text \ Jinformation) 





ARGUMENTS 


related tags 
restrictions 


required 
terminator 


title-text 
Provides heading information. If this argument is not specified, the default 
text “Revision/Update Information” is supplied. 


information 
Provides revision and update information. 





None. 





The <REVISION_INFO> tag is valid only within a title page. 





None. 





DESCRIPTION The <REVISION_INFO> tag labels a section on a title page that provides 


information on what previous books have been superseded by the current 
one. 





EXAMPLE 


See the example in the discussion of the <FRONT_MATTER> tag. 


<RIGHT_LINE> 


<RIGHT_LINE> 


Specifies a line of text that is to be right-justified in the current text margin. 





FORMAT <RIGHT_LINE> (text [ \ { Cae ) 





ARGUMENTS text 
Specifies a line of text to be set on the right-hand side of the page. 
BIGSKIP 
SMALLSKIP 


Specifies that a set amount of vertical space is to precede the element 
identified as a line or block of text. The actual amount of space inserted 
is determined by the doctype’s design. 





related tags °  <LINE> 
: <CENTER_LINE> 


restrictions Invalid in monospaced examples and math. 


Right-adjusted text must fit within the current text margin. If you specify text 
that is too wide, the text formatter issues a warning message, and you should 
examine your output. 


EXAMPLE 


<P>Please include the following information: 
<RIGHT_LINE> (Name) 

<RIGHT_LINE> (Address\smallskip) 
<RIGHT_LINE>(Phone Number) 


This example may produce the following output: 


Please include the following information: 
Name 


Address 
Phone Number 


<RULE> 


<RULE> 


Outputs a rule following headings within a table. 





FORMAT 


<RULE> 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


None. 





° <TABLE_ROW> 


<TABLE_HEADS> 


<SPAN> 


<TABLE_UNIT_HEADS> 





Can be used only with an argument to the <TABLE_ROW> , <TABLE_HEADS> 
or <TABLE_UNIT_HEADS> tags. : 


Must immediately follow the argument text under which the rule is to be 
placed. 





None. 





DESCRIPTION You can specify that a horizontal rule should be included in a table by placing 


a <RULE> tag inside an argument to one of the following tags: 
e¢  <TABLE_ROW> 
¢ = <TABLE_HEADS> 


° <TABLE_UNIT_HEADS> 


The horizontal length of the rule does not correspond to the dimensions of 
the table. The horizontal length of the rule equals the width of the table 
column (or the spanned columns, if the argument also is preceded by a 
<SPAN> tag). 





EXAMPLE 


See the example in the description of the <TABLE_UNIT> tag. 


<S> 


Labels the system portion of a dialog between user and system in an 
interactive example. 





FORMAT 


<S> (text) 





ARGUMENTS 


related tags 


text 
Specifies the text of the system message. 





° <INTERACTIVE> 


<U> 














restrictions Invalid in math. 

required None. 

terminator 

DESCRIPTION The <s> tag labels the system portion of a dialog between the system and 
a user. An example containing this type of dialog needs to have both parts 
identified in order to differentiate the two types of text in the source code, the 
output, or both. 
The <s> and <U> tags are used also to differentiate the system and user 
text inside of examples created with the <EXAMPLE_SEQUENCE> and <EXI> 
tags, in the Software Doctype. For more information on this doctype, refer to 
the VAX DOCUMENT User Manual, Volume 2. 

EXAMPLES 

4] <P>The system prompt <S>($) indicates you can enter a command. 


This example may produce the following output: 


The system prompt $ indicates you can enter a command. 


<S> 


2 <P>The following example of VAXMAIL contains messages from both 
the system and a user of the system: 
<INTERACTIVE> 
<U> (mail) 
<S>(MAIL> )<U> (send) 
<S>(To: )<U>(nodename: : Courtney) 
<S>(/%MAIL-E-NOSUCHUSR, no such user COURTNEY at node NODENAME) 
<ENDINTERACTIVE> 


Note that one space is included after a prompt in an <S> tag argument. 
This example may produce the following output: 


The following example of VAXMAIL contains messages from both the system 
and a user of the system: 


mail 

MAIL> send 

To: nodename: : Courtney 

%MAIL-E-NOSUCHUSR, no such user COURTNEY at node NODENAME 


For another example, see the example in the discussion of the 
<INTERACTIVE> tag. 
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<SAMPLE_TEXT> 


<SAMPLE_TEXT> 





Distinguishes, typographically, an extract of text. 





FORMAT <SAMPLE_TEXT> 





ARGUMENTS None. 











related tags ¢ = <CENTER—LINE> 
restrictions Within the sample text, if you want to show a paragraph, you must label 
it with a <P> tag. The <SAMPLE_TEXT> tag does not provide paragraph 
spacing. 
required <ENDSAMPLE_TEXT> 
terminator 





DESCRIPTION The <SAMPLE_TEXT> tag labels text that requires distinctive formatting. The 
text so labeled will be filled and justified and indented from the normal text 
margins. 





EXAMPLE 


<P>An evolutionary trend toward niche divergence typically results. 
<SAMPLE_TEXT> 

<P>Taken from Brown,T.J.: The Skull of the Pronghorn. The McMullen Company, 
1970. 

<ENDSAMPLE_TEXT> 


This example may produce the following output: 
An evolutionary trend toward niche divergence typically results. 


Taken from Brown,T.J.: The Skull of the Pronghorn. The 
McMullen Company, 1970. 
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<SET_APPENDIX_LETTER> 


<SET_APPENDIX_LETTER> 


Overrides the default appendix letter assigned to an appendix by 
VAX DOCUMENT. 





FORMAT 


<SET_APPENDIX_LETTER> (appendix-letter) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


appendix-letter 


Specifies the letter of the appendix. This argument must be a letter from 
A to Z. 





bd <APPENDIX> 
: <SET_CHAPTER_NUMBER> 


¢ The MILSPEC doctype <SET_APPENDIX_NUMBER> tag. 





This tag should not be used in a file that will be included in a bookbuild 
or element build. Processing this tag in a bookbuild generates a warning 
message. 





None. 





DESCRIPTION 
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Use the <SET_APPENDIX_LETTER> tag to override the default appendix letter 
created by VAX DOCUMENT. The <SET_APPENDIX_LETTER> tag resets 

the current appendix letter; if you specified C as the argument, the next 
<APPENDIX> tag would be Appendix C. 


You should place the <SET_APPENDIX_LETTER> tag in your SDML 

file before the <APPENDIX> tags you want it to affect, because the 
<SET_APPENDIX_LETTER> tag affects only the <APPENDIX> tags that follow 
it. The new appendix letter you specify resets the numbering for all following 
appendixes. For example, if you use the <SET_APPENDIX_LETTER> tag to 

set the appendix letter to “C,” the next appendix will be Appendix C, the 
appendix following that appendix will be Appendix D, and so on. 


<SET_APPENDIX_LETTER> can be used multiple times in a SDML file. 


<SET_APPENDIX_LETTER> 





EXAMPLE In the following example the appendix “Error Messages” is explicitly set to 
C using the <SET_APPENDIX_LETTER> tag. This will cause any subsequent 
appendixes to be numbered beginning with the letter D unless another 
<SET_APPENDIX_LETTER> tag is used to again reset the current appendix 
letter. 


<SET_APPENDIX_letter>(C) 

<APPENDIX> (Error Messages\error_msg_ap) 
<p> 

The following error messages... 


9-197 


<SET_CHAPTER_NUMBER> 


<SET_CHAPTER_NUMBER> 


Overrides the default chapter number assigned to a chapter by 
VAX DOCUMENT. 





FORMAT 


<SET_CHAPTER_NUMBER> (chapter-number) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


chapter-number 
Specifies the number of the chapter. This argument must be a positive 
integer. 





° <CHAPTER> 


® <SET_APPENDIX_LETTER> 





This tag should not be used in a file that will be included in a bookbuild 
or element build. Processing this tag in a bookbuild generates a warning 
message. 





None. 


DESCRIPTION 
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Use the <SET.CHAPTER_NUMBER> tag to override the default chapter number 
created by VAX DOCUMENT. The <SET_CHAPTER_NUMBER> tag resets the 
current chapter number; if you specify 13 as the chapter number, the next 
<CHAPTER> tag becomes Chapter 13. This numbering also affects all other 
<CHAPTER> tags in your SDML file so that the subsequent chapter becomes 
Chapter 14, and so on. 


The <SET_CHAPTER_NUMBER> tag should be placed in your SDML file before 
the <CHAPTER> tags that you want to affect, because the <SET_CHAPTER_ 
NUMBER> tag affects only the <CHAPTER> tags that follow it. 


The new chapter number you specify resets the numbering for all following 
chapters. For example, if you use the <SET.CHAPTER-NUMBER> tag to set the 
chapter number to 13, the next chapter will be Chapter 13, and the chapter 
following that chapter will be Chapter 14, and so on. 


The <SET_CHAPTER_NUMBER> can be used multiple times in an SDML file. 


<SET_CHAPTER_NUMBER> 


‘ 





EXAMPLE In the following example the chapter is set to 13 using the 
<SET_CHAPTER_NUMBER> tag. This will cause any subsequent chapters 
to be numbered beginning with number 14 unless another <SET_CHAPTER_— 
NUMBER> tag is used to again reset the current chapter number. 


<SET_CHAPTER_NUMBER> (13) 

<CHAPTER> (Supported Devices\sup_dev_chap) 
<p> 

The primary supported devices... 
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 <SET_CONDITION> 


<SET_CONDITION> 


Creates or removes a condition-name. 





FORMAT 


<SET_CONDITION> (condition-name[ \ REMOVE]) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


condition-name 
Specifies a name used to conditionalize a portion of your SDML file. This 
name is limited to 28 characters in length. 


REMOVE 


Causes the condition-name to be removed. 





e <CONDITION > 





None. 





None. 





DESCRIPTION The <SET_CONDITION> tag is used to create or remove a condition-name. 


Conditions are specified with the <CONDITION> tag. 
For a complete explanation of creating conditional text, refer to Chapter 4. 


Normally, a condition-name is created at the front of your input and remains 
in effect for the whole of the input file. In the rare occasion when you want to 
process a portion of the input without the condition-name, it can be removed 


‘by repeating the <SET_CONDITION> tag with the REMOVE argument. 


You can use the /CONDITION qualifier on the DOCUMENT command line 
instead of placing the <SET_CONDITION> tag into your file. For example, 
you might use the command line qualifier “/CONDITION=local” instead of 
putting “ <SET_CONDITION> (local)” in your input file. 





EXAMPLE 


See the example under the discussion of the <CONDITION> tag. 


<SINGLE_QUOTE> 





<SINGLE_QUOTE> 


Outputs, within text, a single quotation mark as it appears on a keyboard. 





FORMAT 


<SINGLE_QUOTE> 





ARGUMENTS 


related tags 


None. 





® <DOUBLE_QUOTE> 


® <QUOTE> 











restrictions None. 

required None 

terminator 

DESCRIPTION The reason for the <SINGLE_QUOTE> tag lies in a mismatch between 


conventions used in the typesetting world and conventions used in the 
computing world. Your terminal keyboard has two possible characters you 
can use for quotation marks: the " which is the ASCII 34 and the ’, which 
is the ASCII 39. Neither distinguishes between open quotation marks and 
closed quotation marks. You use the same character twice to enclose a word 
in quotation marks: : 


"a quoted string" 
or 
?a quoted string’ 


Typesetters, on the other hand, scrupulously distinguish between open 
quotation marks and closed quotation marks. The former look like small 
sixes; the latter; like small nines. (Actually, in the text font used on the LNO1, 
the open quotation marks look like splinters with their points up; the closed 
quotation mark looks like splinters with their points down.) Look carefully at 
any typeset document and you will immediately see the difference between 
open and closed quotation marks. 


To obtain a single quotation mark in your output, looking as it does when 
shown on the terminal (as an apostrophe), use the <SINGLE_QUOTE> tag. If 
you simply use the keyboard single quotation mark instead of the tag, your 
output will contain unmatched closed single quotation marks—one half of 
what should be a matched pair. (See the example section.) If you use the 
tag, your output will contain a single quotation mark that looks like the one 
produced by the terminal keyboard. 
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<SINGLE_QUOTE> 





EXAMPLES 


1 <P>You can cause the translation of a symbol by using a single 
quotation mark (<SINGLE_QUOTE>) directly in front of it. 


This example shows the use of the <SINGLE_QUOTE> tag. It may produce 
the following output: 


You can cause the translation of a symbol by using a single quotation mark (’) 
directly in front of it. 


2 <P>You can cause the translation of a symbol by using a single 
quotation mark (’) directly in front of it. 


This example shows what your output would be like without using the tag, 
but just entering the character from the keyboard. 


You can cause the translation of a symbol by using a single quotation mark (’) 
directly in front of it. 
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<SPAN> 





<SPAN> 


Specifies that the accompanying argument in a table row or a table head 
should span more than one table column. 


FORMAT <SPAN> (n[\ LEFT)) 








ARGUMENTS "7 


Specifies the number of table columns to be spanned by the argument. 


LEFT 


Specifies that the text of the argument should be aligned to the left in the 
left-most of the spanned columns. If this argument is omitted the text of the 
argument is centered in the spanned columns. 





related tags ¢  <TABLE_HEADS> 
¢  <TABLE_UNIT_HEADS> 





restrictions Can be used only within an argument to the <TABLE_ROW>, <TABLE 
HEADS> , Or <TABLE_UNIT_HEADS> tags. 


Must immediately precede the argument text. 





required None. 
terminator 





DESCRIPTION The <sPAN> tag specifies that the argument text that follows the tag should 
not be confined to a single table column, but should span additional columns. 
The text is displayed without regard for the gutter that separates the columns. 
The text is normally centered in the spanned columns, unless the LEFT 
argument is supplied. 


If the text length exceeds the width of the spanned columns it is broken at a 
word boundary and displayed on additional table lines. Any additional lines 
of text are centered or left justified to agree with the alignment of text in the 
first line. 


You may want to code a table row to span the last several columns of a table. 
See the second example below for a sample of such coding. 
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<SPAN> 





EXAMPLES 


4 An example of spanned table unit heads can be seen in the example of 
<TABLE_UNIT>. 


2 <TABLE> 
<TABLE_SETUP>(5\9\9\9\9) 
<TABLE_ROW>(\<SPAN>(2\Small Fixture) \<SPAN>(2\Large Fixture) ) 
<TABLE_ROW> (Component \Minimum\Maximum\Minimum\Maximum) 
<ENDTABLE> 


The output of this example is expected to look approximately like this: 


Small Fixture Large Fixture 
Component Minimum Maximum Minimum Maximum 


However, <SPAN> will actually center “Small Fixture” correctly, but “Large 
Fixture” may be pushed too far to the right: 
(Small Fixture) (Large Fixture) 


Component Minimum Maximum Minimum Maximum 


This occurs because the <SPAN> tag attempts to span the last column to 
the margin. To fix this problem, code the table for an additional column and 
specify a width for that additional column, thereby fixing the distance that is 
spanned: 

<table> 

<table_setup>(6\8\8\8\8\8) 

<table_row>(\<span>(2) (Small Fixture) )\<span>(2) (Large Fixture) ) 


<table_row> (Component \Minimum\Maximum\Minimum\Maximum) 
<endtable> 


Produces: 


(Small Fixture) (Large Fixture) 
Component Minimum Maximum Minimum Maximum 
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<SPECIAL_CHAR> 


<SPECIAL_CHAR> 


Provides access to special characters that are not available on the terminal 


keyboard. 





FORMAT 


<SPECIAL_CHAR> (keyword) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


keyword 
Specifies a keyword associated with the special character you want to produce 
in your output file. The following are valid keywords: 


Keyword Character 
FULL__DIAMOND 
TRADEMARK_SYMBOL 
REGISTERED_SYMBOL 
SECTION_SIGN 

DAGGER 

DOUBLE DAGGER 
OPEN_DOUBLE_BRACKET 
CLOSE_DOUBLE_BRACKET 





® <MCS> 


° <MATH_—CHAR> 





The character must be a non-math character. 





None. 





DESCRIPTION The <SPECIAL_CHAR> tag provides access to special characters that are not 


available on the terminal keyboard. 
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<SPECIAL_CHAR> 





EXAMPLE 


%COPY-I-COPIED, $DISK1:[MYDIRECTORY] MYFILE.PLI ;5<SPECIAL_CHAR>(FULL_DIAMOND) 
copied to $DISK1: [YOURDIRECTORY] YOURFILE.PLI;5 


In this example, the special character # is used in an example of terminal 


output to show that text wraps at the end of a line. The example may 
produce the following output: 


p aae $DISK1: [MYDIRECTORY] MYFILE.PLI;5 


copied to $DISK1: [YOURDIRECTORY] YOURFILE.PLI;5 
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<SUBHEADx> 


<SUBHEADx> 


Marks an unnumbered subsidiary heading. 





FORMAT <SUBHEAD1 > (heading-text) 
<SUBHEAD2> (heading-text) 





ARGUMENTS heading-text 
The text of the subsidiary heading. 





related tags e <HEAD1> through <HEAD6> 


. <CHEAD> 








restrictions None. 
required None. 
terminator 





DESCRIPTION The <SUBHEADI> and <SUBHEAD2> tags label unnumbered subsidiary 
headings. Each reflects a logical hierarchy within the structure of the text. 


These subheadings are not numbered and do not appear in the table of 
contents. They cannot be readily used for cross-references and should be 
used only when the clarity of your exposition requires such a fine level of 
distinction. 


In some book doctypes, the distinction is made between <SUBHEAD1> and 
<SUBHEAD2> by making <SUBHEAD2> a run-in heading. The doctype 
design controls the text formatter’s placement of the text following the 
<SUBHEAD2> . Whether or not you expect the heading to be run-in, always 
tag the text element following the heading (for example, always mark a 
paragraph with a <P> tag). 





EXAMPLE 


<SUBHEAD1>(Using a Subhead) 

<P>The use of subheads should be restricted to occasions when the clarity 

of your exposition absolutely requires one. 
This example might produce output like the following: 
Using a Subhead 


The use of subheads should be restricted to occasions when the clarity of 
your exposition absolutely requires one. 
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<TABLE> 


<TABLE> 


Begins a sequence of columnar data. 





FORMAT <TABLE> /[(table-caption[ \ symbol-name))] 





ARGUMENTS _ table-caption 
Specifies the text of the caption to be associated with the table. The table 
caption and the associated table number will be written to the table of 
contents for the document. 


Note that the presence of this argument indicates that the table is a formal, 
numbered table. If the body of the table spans more than a single page of 
text, the table caption is repeated on each page on which the table continues. 


symbol-name 

Specifies the symbolic identifier to be associated with the table. The symbol 
identifier will be assigned a numeric value which will be the current table 
number. The symbol and its value are placed in the symbol table. 


The symbol name can consist of up to 64 alphanumeric characters or 
underscores. It must not begin with a leading underscore. 





related tags e = <TABLE_ATTRIBUTES> 
e  <TABLE_SETUP> 
©  <TABLE_HEADS> 
°  <TABLE_ROW> 
¢  <TABLE_FILE> 
© = <TABLE_UNIT> 
© <TABLE_KEY> 
©  <TABLE_SPACE> 
e  <SPAN> 


e <RULE> 


restrictions The <TABLE> tag is not valid in monospaced examples, in math, or in 
figures. 


required <ENDTABLE> 
terminator 
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<TABLE> 


EXAMPLE 


<P>An expression can evaluate to either an integer or 
a string value, depending on the types of values used in the expression 
and the operations used to manipulate them. 
<REFERENCE>(express_modes_tab) summarizes the rules 
for determining the mode of an expression. . 
<TABLE>(Rules for Determining Expression Modes\express_modes_tab) 
<TABLE_ATTRIBUTES> (MULTIPAGE) 
<TABLE_SETUP> (2\33) 
<TABLE_HEADS> (Expression\Value Type) 
<TABLE_ROW>(Integer value\Integer) 
<TABLE_ROW> (String value\String) 
<TABLE_ROW> (Integer lexical function\Integer) 
<TABLE_ROW_BREAK> (first) 
<TABLE_ROW> (String lexical function\String) 
<TABLE_ROW>(Integer symbol\Integer) 
<TABLE_ROW> (String symbol\String) 


<ENDTABLE> 


This example shows how to produce a two-column table. This example may 
produce the following output: 


An expression can evaluate to either an integer or a string value, depending 
on the types of values used in the expression and the operations used to 
manipulate them. Table x—x summarizes the rules for determining the mode 
of an expression. 


Table x—x Rules for Determining Expression Modes 








Expression | Value Type 
Integer value Integer 
String value String 
Integer lexical function Integer 
String lexical function _ String 
Integer symbol Integer 
String symbol String 
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<TABLE_ATTRIBUTES > 





<TABLE_ATTRIBUTES > 


Requests special formatting. 





oan <TABLE_ATTRIBUTES> ( { MULTIPAGE | 
KEEP 


[WIDE] 
[MAXIMUM] 





ARGUMENTS MULTIPAGE 


Indicates that the table is either of the following: 
e Longer than a page 
¢ Allowed to break across pages 


This is the default. If MULTIPAGE is specified, the <TABLE_ROW_BREAK> tag 
can be used to control page breaks. 


KEEP 


Indicates that the table must be kept on one page. If there is not enough 
room on the current page, a new page is output. If the table exceeds the 
length of a page, the text formatter issues a warning message. Not all the 
table will print. 


WIDE 


Specifies that the width of the table exceeds the document's default width for 
text. Depending on the document type, this argument may be interpreted as 
follows: 


e If the document style contains a left margin area that is normally used for 
headings, the table’s width will span that area as well as the normal text 
area. 


e If the document uses a multicolumn format, the table suspends 
multicolumn output while the table is processed. The table is output, 
and then multicolumn output is restored. 


MAXIMUM 


Indicates that the table can exceed the width of the page, even if WIDE is 
specified. The text of the table will be adjusted to a smaller point size. Note 
that if this argument is not specified, and if a table is determined during text 
formatting to be too wide, the text formatter will adjust the size of the text 
automatically. 





related tags °  <TABLE> 
bg <TABLE_SETUP> 


<TABLE_ATTRIBUTES > 











restrictions 
¢ Must be in the context of a table. 
¢ Must precede the <TABLE_SETUP> tag. 
e WIDE and MAXIMUM might not produce error-free output for 
monospaced output devices. 
required None. 
terminator 
EXAMPLE 
<TABLE> (Equivalence 


Names for Default Process Logical Names\equiv_names_proc_tab) 
<TABLE_ATTRIBUTES> (WIDE\KEEP) 
<TABLE_SETUP> (4\8\10\12) 
<TABLE_HEADS> (Logical Name\Interactive\Batch\Command Procedure) 
<TABLE_ROW> (SYS$COMMAND\Terminal\Disk\Terminal) 
<TABLE_ROW> (SYS$DISK\Disk\Disk\Disk) 
<TABLE_ROW> (SYS$INPUT\Terminal\Disk\Disk) 
<TABLE_ROW> (SYS$ERROR\Terminal\Log file\Terminal) 
<TABLE_ROW> (SYS$LOGIN\Directory\Directory\Directory) 
<TABLE_ROW> (SYS$NET\\\) 
<TABLE_ROW> (SYS$OUTPUT\Terminal\Log file\Terminal) 
<TABLE_ROW> (SYS$SCRATCH\Directory\Directory\Directory) 
<TABLE_ROW>(TT\Terminal\Null device\Terminal) : 
<ENDTABLE> 


This example produces the following output: 


Table x—x Equivalence Names for Default Process Logical Names 


Logical Name Interactive Batch Command Procedure 
SYS$COMMAND Terminal Disk Terminal 

SYS$DISK Disk Disk Disk 

SYSS$INPUT Terminal Disk Disk 

SYS$ERROR Terminal Log file Terminal 

SYS$LOGIN Directory Directory Directory 

SYS$NET 

SYSS$OUTPUT Terminal Log file Terminal 
SYS$SCRATCH _ Directory Directory Directory 

TT Terminal Null device ' Terminal 





9-211 


<TABLE_FILE> 





<TABLE_FILE> 


Causes a separate file containing a formal table to be included in the SDML 
input file. 





FORMAT  — <TABLE_FILE> (file-spec) 





ARGUMENTS _file-spec 


The file specification of the file to be included. If.a logical name is specified 
instead, and the SDML input file is an element of a book, you can define 
the logical name using an <INCLUDES_FILE> tag in the book’s profile. If the 
source file is not an element of a book, or if the profile does not contain the 
-<INCLUDES_FILE> tag, be sure to define the logical name before processing 
the file through VAX DOCUMENT. 





related tags ¢  <TABLE> 





restrictions Can be used only in the context of a <TABLE> tag. 


The <TABLE_FILE> tag must be placed after the <TABLE> tag. 





required None. 
terminator 


DESCRIPTION The <TABLE_FILE> tag causes the entire contents of a specified file to be 
included at this point in the SDML file. (It is identical in action to the 
<INCLUDE> tag.) The included file should be an SDML file containing a 
completely coded table. 


By keeping a table in a separate SDML file, you can include the table in more 
than one document, or in chapters of the same document, without having 

to reproduce the code. In each location, the table can be given a different 
number. 





EXAMPLES 


<TABLE> (Default VMS File Types\Stand_Filetypes_Tab) 
<TABLE_ATTRIBUTES> (wide) 
<TABLE_FILE>(Standard_Filetypes) 

<ENDTABLE> 


This example shows a wide table that is contained in a separate file. The 
logical name of the file (Standard_Filetypes) should be recorded in the profile 
along with the proper file specification for the file. See the next example for a 
sample profile entry. | 
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<TABLE_FILE> 


It should be noted that this included table file will not process individually. 
It will only process when included in another 2DME file that specifies the 
<TABLE> and <ENDTABLE> tags. 


<REFERENCE>(command_sum_tab) lists all the commands. 
<TABLE_FILE>(endlist.sdml) 


In this example, the file ENDLIST.SDML may contain all the tags required for 
the table: 


<TABLE>(Command Summary\command_sum_tab) 
<TABLE_ATTRIBUTES> (Multipage) 
<TABLE_SETUP> (2\18) 


This example assumes that the table is being used in only one document. 
Placing the table in a separate file allows you to process it individually, or in 
the context of the file in which it occurs. 
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<TABLE_HEADS> 


<TABLE_HEADS> 


Specifies column headings for each column in the table. 





FORMAT 


<TABLE_HEADS> (col-heading| \ col-heading...}) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


col-heading 

Specifies the heading for each column; the first argument is the heading for 
the first column. Up to nine arguments can be specified, depending on the 
number of columns in the table. 





° <TABLE_UNIT> 
be <TABLE_HEADS> 
e <SPAN> 


° <RULE> 





Only used in the context of a <TABLE> tag. 


Maximum of nine column headings. 





None. 





DESCRIPTION This tag is not required in a table tags sequence. However, it allows you to 


specify a heading for each column of a table if headings are needed. 


A heading can be any length, and is automatically formatted correctly on one 
or more lines (see the long heading in the example in <TABLE_ROW> ). 


Within tables, the <TABLE_HEADS> tag can be used to specify multipage 
headings for a table. It can also be used to place new headings in the middle 
of a table. However, it can not be used in a table unit. 





EXAMPLE 


See the example for the <TABLE_ROW> tag. 


<TABLE_KEY> 


<TABLE_KEY > 


Begins a key or legend for a table. 





FORMAT 


<TABLE_KEY> 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


None. 





bg <TABLE_KEYREF> 


° <FOOTNOTE> 





Can be used only within the context of a table. 


Must appear immediately after the tag <TABLE_SETUP> , either before or after 
any <FOOTNOTE> tags. 


When a <TABLE_KEY> is used, the number of possible footnotes for the same 
table is reduced from 12 to 11. 


The tags that can be used between <TABLE_KEY> and <ENDTABLE_KEY> are 
restricted to the <P>, <LIST> and emphasis tags. For example, you cannot 
use a <TABLE_ROW> tag within the table key. 


The <TABLE_KEY> tag is not valid in a nested table. <TABLE_KEY> must 
follow the <TABLE_SETUP> tag for the outermost table. 





<ENDTABLE_KEY> 


DESCRIPTION Abbreviations or special terms are often used in a table, either in the column 


eadings, or in the entries of the table. The table may then need a key or 
legend printed below it that explains the special terms. The <TABLE_KEY> 
tag begins such a table key. 


A table key differs from a table footnote as the table key is not numbered and 
does not refer to a callout in the table. Only one table key can be declared 
for a table, whereas up to 12 footnotes are possible. 


The table key is declared immediately after the <TABLE_SETUP> tag that 
begins the table and before the first tag that begins the table rows. This 
placement is identical to the placement for footnotes in a table. If footnotes 
are present also, they either can precede or follow the table key declaration. 


The table key is printed at the foot of the table, following any footnotes. It is 
printed only if the <TABLE_KEYREF> tag appears in the table. Place <TABLE_ 
KEYREF> anywhere in the argument list that supplies the column heads. This 
placement guarantees that the table key is printed at the foot of the table and 
on each page of a multipage table. (If you want the table key to appear only 
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<TABLE_KEY> 


on selected pages of a multipage table, place <TABLE_KEYREF> with the table 


row tags for the selected pages.) 





EXAMPLE 


<table>(Compatability of Lock Modes\lock_tab) 
<table_attributes>(wide\keep) 
<table_setup>(7\10\5\5\5\5\5) 


<table_key> 
<emphasis>(Key to Lock Modes\bold) 
<list>(simple) 
<le>NL---Null lock 
<le>CR---Concurrent read 
<le>CW---Concurrent write 
<le>PR---Protected read 
<le>PW---Protected write 
<le>EX---Exclusive lock 
<ENDLIST> 
<endtable_key> 


<table_heads>(Mode of Requested\ 


<span>(5)Mode of Currently Granted Locks<rule>) 


<table_heads> (Lock<table_keyref>\NL\CR\CW\PR\PW\EX) 
<table_row>(NL\Yes\Yes\Yes\Yes\Yes\Yes) 
<table_row>(CR\Yes\Yes\Yes\Yes\Yes\No) 
<table_row>(CW\Yes\Yes\Yes\No\No\No) 
<table_row>(PR\Yes\Yes\No\Yes\No\No) 
<table_row>(PW\Yes\Yes\No\No\No\No) 
<table_row>(EX\Yes\No\No\No\No\No) 


<endtable> 


This example produces the following output: 


Table x—x Compatibility of Lock Modes 


sana d Mode of Currently Granted Locks 
Lock NL CR CW PR PW 
NL Yes Yes Yes Yes Yes 
CR Yes Yes Yes Yes Yes 
CW Yes Yes Yes No No 
PR Yes Yes No Yes No 
Pw Yes Yes No No No 
EX Yes No No No No 


Key to Lock Modes 


NL—Null lock 
CR—Concurrent read 
CW—Concurrent write 
PR——Protected read 
PW—Protected write 
EX—Exclusive lock 
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EX 
Yes 
No 
No 
No 
No 
No 


<TABLE_KEYREF> 





<TABLE_KEYREF> 


Specifies that a table key should be printed below the table (or portion of 
the table) in which this tag appears. 





FORMAT 


<TABLE_KEYREF> 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


None. 





e <TABLE_KEY> 





Can be used only within the context of a table in which <TABLE_KEY> is 


_ specified. 


Invalid in nested tables. 





None. 


DESCRIPTION 


The <TABLE_KEYREF> tag specifies that the table key (defined with the 
<TABLE_KEY> ... <ENDTABLE_KEY> tags) should be printed at the foot of 
the table. The table key is printed only if the <TABLE_KEYREF> tag appears 
in the table. 


When the table is a multipage table, the table key can be printed at the foot 
of any or all portions of the table. 


If you want the table key printed at the foot of all portions of a multipage 
table, place the <TABLE_KEYREF> tag anywhere in the argument list to the 
<TABLE_HEADS> tag that defines the table’s column headings. This will 

cause the table key to be repeated on each page of the table. 


If the table key is to be printed only on specified pages of a multipage table, 
place the <TABLE_KEYREF> tag in the <TABLE_ROW> tags in the reference to 
the table key. 





EXAMPLE 


See the example under the discussion of the <TABLE_KEY> tag. 


<TABLE_ROW> 


<TABLE_ROW> 


Specifies text for each column in the current table. 





FORMAT 


<TABLE_ROW> (column-text1[,column-text2y,...]]) 





ARGUMENTS 


_——_te Si 


related tags 


restrictions 


required 
terminator 


column-text 

Specifies text for a single column in the table row. The number of arguments 
specified to this tag is dependent on the number of columns specified for 

the table. This value is specified in the <TABLE_SETUP> tag. If the number 
of arguments to <TABLE_ROW> exceeds the number of columns currently 

in effect for the table, the excess columns are ignored. If the number of 
arguments is less than the number of columns currently in effect for the table, 
unspecified columns are output as blanks. 





bs <SPAN> 
ba <RULE> 


© <TABLE_ROW_BREAK> 





Must be used in the context of a table. 


If the text in a single table row column exceeds the depth of an output page, 
the text formatter issues an error message and terminates processing. 


Page breaking of long table rows may be controlled, with additional 
restrictions, with the <VALID_ROW_BREAK> tag. 





None. 





DESCRIPTION The <TABLE_ROW> tag specifies text for each column in the current table. 





EXAMPLE 


<P> An expression can evaluate to either an integer or 

a string value, depending on the types of values used in the expression 
and the operations used to manipulate them. 
<REFERENCE>(express_modes_tab) summarizes 

the rules for determining the mode of an expression. 


IN EM We MOEL> (#30) py a | 


<TABLE_ROW> 


<TABLE>(Rules for Determining Expression Modes\express_modes_tab) 
<TABLE_ATTRIBUTES> (MULTIPAGE) 
<TABLE_SETUP> (2\43) 
<TABLE_HEADS>(Expression\Value Type) 
<TABLE_ROW>(Integer value\Integer) 
<TABLE_ROW> (String value\String) 
<TABLE_ROW>(Integer lexical function\Integer) 
<TABLE_ROW>(String lexical function\String) 
<TABLE_ROW> (Integer symbol\Integer) 
<TABLE_ROW> (String symbol\String) 
<TABLE_ROW>(Any value .AND. or .OR. any value\Integer) 
<TABLE_ROW> (Any value\Integer) 
<TABLE_ROW>(Any value\Integer) 

<ENDTABLE> 


This example shows how to produce a two-column table. This example may 
produce the following output: 


An expression can evaluate to either an integer or a string value, depending 
on the types of values used in the expression and the operations used to 
manipulate them. Table x—x summarizes the rules for determining the mode 
of an expression. 


Table x—x Rules for Determining Expression Modes 








Expression . Value Type 
Integer value Integer 
String value String 
Integer lexical function Integer 
String lexical function String 
Integer symbol ae Integer 
String symbol String 

Any value .AND. or .OR. any value Integer 

Any value Integer - 
Any value Integer 
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<TABLE_ROW_BREAK> 


<TABLE_ROW_BREAK> 


Specifies the boundaries within which a long table can be broken onto a 
new page. 








FORMAT <TABLE_ROW_BREAK> ( } FIRST ! ) 
LAST 
ARGUMENTS FIRST 
LAST 


related tags 


Specifies the bounds within which a multipage table may be broken. After 
<TABLE_ROW_BREAK> (FIRST) is specified, any row in the table up to the 
occurrence of <TABLE_ROW_BREAK> (LAST) is treated as a suitable page- 
breaking point. 





e <NESTED_TABLE_BREAK> 


. <VALID_TABLE_ROW_BREAK> 











restrictions The <TABLE_ROW_BREAK> tag is invalid in a table specified with the KEEP 
option, or in a table that is specified in an argument to a <TABLE_ROW> tag. 
required None. 
terminator 
The <TABLE _ROW_BREAK> tag provides an allowable place for a long table to 


DESCRIPTION 


be broken across pages. 


Tables in VAX DOCUMENT are, by default, multipage tables. If 
<TABLE_ROW_BREAK> is not specified to provide the text formatter with 
reasonable guidelines to break tables across pages, the text formatter will 
nonetheless select page breaks. The page breaks selected will not always be 
suitable. Therefore, use of the <TABLE_ROW_BREAK> tag is recommended. 


By default, the text formatter will not break a page within a table row. With 
some restrictions, valid page breaks within table rows can be specified using 
<VALID_TABLE_ROW_BREAK> . 


Nested tables (that is, tables that are specified within an argument to a 
<TABLE_ROW> tag) can, with some restrictions, be given valid page breaks 
using the <NESTED_TABLE_BREAK> tag. 


<TABLE_ROW_BREAK> 





EXAMPLE 


<P> An expression can evaluate to either an integer or 

a string value, depending on the types of values used in the expression 
and the operations used to manipulate them. 

Table <REFERENCE>(express_modes_tab) summarizes 

the rules for determining the mode of an expression. 


<TABLE>(Rules for Determining Expression Modes\express_modes_tab) 
<TABLE_ATTRIBUTES> (MULTIPAGE) 
<TABLE_SETUP> (2\43) 
<TABLE_HEADS>(Expression\Value Type) 
<TABLE_ROW>(Integer value\Integer) 
<TABLE_ROW> (String value\String) 
<TABLE_ROW>(Integer lexical function\Integer) 
<TABLE_ROW> (String lexical function\String) 
<TABLE_ROW>(Integer symbol\Integer) 
<TABLE_ROW> (String symbol\String) 
<TABLE_ROW>(Any value .AND. or .OR. any value\Integer) 
<TABLE_ROW>(Any value\Integer) 


<COMMENT>(OK to break after this) 
<TABLE_ROW_BREAK> (first) 
<TABLE_ROW>(Any value\Integer) 
<TABLE_ROW>(Integer value\Integer) 
<TABLE_ROW>(String value\String) 
<TABLE_ROW>(Integer lexical function\Integer) 
<TABLE_ROW>(String lexical function\String) 

<COMMENT> (Don’t break after this) 
<TABLE_ROW_BREAK> (last) 


<TABLE_ROW>(Integer symbol\Integer) 

<TABLE_ROW>(String symbol\String) 

<TABLE_ROW>(Any value .AND. or .OR. any value\Integer) 
<TABLE_ROW> (Any value\Integer) 

<TABLE_ROW>(Any value\Integer) 


<ENDTABLE> 


This example shows how to produce a two-column table. This example may 
produce the following output: 


An expression can evaluate to either an integer or a string value, depending 
on the types of values used in the expression and the operations used to 
manipulate them. Table x—x summarizes the rules for determining the mode 
of an expression. . 


Table x—x Rules for Determining Expression Modes 








Expression Value Type 
Integer value Integer 
String value String 
Integer lexical function Integer 
String lexical function . String 
Integer symbol Integer 
String symbol String 

Any value .AND. or .OR. any value Integer 

Any value Integer 

Any value Integer 
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<TABLE_ROW_BREAK> 


Table x—-x (Cont.) Rules for Determining Expression Modes 


Expression Value Type 
Integer value Integer 
String value String 
integer lexical function Integer 
String lexical function String 
Integer symbol Integer 
String symbol String 

Any value .AND. or .OR. any value Integer 

Any value Integer 

Any value Integer 


9-222 


ES | <TABLE_SETUP> 


<TABLE_SETUP> 


Declares the number of columns in a table and the effective (approximate) 
width values to be assigned to each column. 


J 


pon et De "<TABLE_SETUP> (number \ width, [ . . 


ARGUMENTS 


related tags 


restrictions 


required 
terminator 





pas Re \ wi CO a crber- 1 )) 


number 
Specifies the number of columns in the table. The argument must be a 
numeric argument in the range of 1 through 9. 


Specify the approximate widths of columns 1 through number — 1. The last 
column, whose width is unspecified, uses the balance of the right-hand side 
of the page of output. 


The width unit is measured in characters. However, this is an approximante 
measurement because the width of each character depends on the fonts being 
used in the doctype. You may need to modify the width argument after 
processing the table and viewing the output. 





. <TABLE—_ATTRIBUTES > 





The <TABLE_SETUP> tag must be used in the context of a table. 


If <TABLE_SETUP> is omitted from a sequence of <TABLE> tags, no table 
will be included in your output. 


The <TABLE_SETUP> tag must be placed after the <TABLE_ATTRIBUTES> tag 
and before the <TABLE_ROW> tags in the table tag sequence. 





None. 


DESCRIPTION 


The arguments to this tag define the number of columns in a multicolumn 
table and the approximate width of each column. A table can have a 
maximum of nine columns. 


In the width argument, define the width of each column except the last. This 
last column width is supplied automatically. 


Values specified in <TABLE_SETUP> are checked during processing to 

determine whether the values specified exceed or approach the table’s 

threshold for the given document type. Warning or error messages are 
issued as appropriate. 
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<TABLE_SETUP> 


If the table-column widths do not allow the table to fit within the page width, 
the text processor substitutes a smaller point size for the font in which the 
table is set. It then makes another attempt to fit the table within the text 
margin. 





EXAMPLE 


<TABLE>(Names of Cheeses from Around the World\cheeses_tab) 
<TABLE_ATTRIBUTES> (wide\multipage) 

<TABLE_SETUP> (4\14\14\14) 

<TABLE_HEADS> (Cheese Name\Location of production\Type\Color) 
<TABLE_ROW>(Spreadable\Great Britain\Curdled\White) 
<TABLE_ROW>(Smooth\Switzerland\Aged and Tasty\0ff yellow) 
<TABLE_ROW>(Chunky\American\Bland\Yellow) 

<ENDTABLE> 


This example may produce the following output: 


Table x—x Names of Cheeses from Around the World 





Location of 
Cheese Name production Type Color 
Spreadable Great Britain Curdled White 
Smooth Switzerland Aged and Tasty Off yellow 
Chunky — American Bland Yellow 





<TABLE_SPACE> 


<TABLE_SPACE> 


Marks the space required for a table that will be pasted in during final 
production. 





FORMAT <TABLE_SPACE> (value\text) 





ARGUMENTS value 


Specifies the amount of vertical space to be left on the page, specified in picas. 
(A pica is approximately one sixth of an inch.) 


text 

Specifies text that describes the status of the table (“To Be Set”, an art file 
number, or some other note). The text will be output in the middle of the 
space left for the table. 











related tags None. 

restrictions Must be used inside a <TABLE_ROW> tag. 
required None. 

terminator 





DESCRIPTION The <TABLE_SPACE> tag causes a blank space to be left for a table that will 
be pasted in by hand during final production. The value in the <TABLE_ 
SPACE> tag should be specified in picas, a scale used by typesetters. There 
are approximately six picas to the inch. Thus, if the table to be pasted in is 
four inches high, you should specify 24 picas. If you do not specify a value, a 
default value of eight picas is used. 


If you specify some descriptive text in the second argument, that text is output 
in the middle of the space left for the table. 





EXAMPLE | 


<TABLE>(Script Control Blocks\script_tab) 
<TABLE_SETUP> (2\22) 
<TABLE_HEADS> (Block ID\Layout) 
<TABLE_ROW>(SCBEG; starts the scripting 
sequence\<TABLE_SPACE>(4\SCBEG diagram) ) 


<TABLE_ROW>(SCMID; gives the body of the script\<TABLE_SPACE>(4\SCMID 
diagram) ) 


<TABLE_ROW>(SCEND; ends the scripting sequence\<TABLE_SPACE> (4\SCEND 


diagram) ) 
<ENDTABLE> 


This example shows how a table is coded with the <TABLE_SPACE> tag. In 
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<TABLE_SPACE> 


this example, the <TABLE_SPACE> tags reserve space inside of each table row 
for three separate diagrams. 


Table x—x Script Control Blocks 


Block ID Layout 


SCBEG; starts the scripting 
sequence 


SCBEG diagram 


SCMID; gives the body of the 
script 


SCMID diagram 


SCEND; ends the scripting 
sequence 


SCEND diagram 
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<TABLE_UNIT> 





<TABLE_UNIT> 


Begins a portion of a table containing rows that are to be grouped as 
logical units. 





FORMAT | <TABLE_UNIT> 





ARGUMENTS None. 








related tags e  <TABLE_UNIT_HEADS> 
restrictions Can be used only within the context of a table established with the <TABLE> 
. tag. 


The table must not be declared with the KEEP argument. 


If table units are long and you want to allow them to break across pages, you 
must use the <TABLE_ROW_BREAK> (first) and <TABLE_ROW_BREAK> (last) tags 
within the bounds of <TABLE_UNIT> and <ENDTABLE_UNIT> . 





required <ENDTABLE_UNIT> 
terminator 





DESCRIPTION The <TABLE_UNIT> tag and its terminating tag, <ENDTABLE_UNIT> , are 
used to subdivide a table by grouping some number of rows of the table into 
a unit. The table unit can be given a heading. 


EXAMPLE 


<Table>(String Passing Techniques Used by the Run-Time Library\Str_Tech_Tab) 
<X>(String Passing Techniques Used by the Run-Time Library) <comment>(*) 
<TABLE_ATTRIBUTES> (WIDE\MULTIPAGE) 

<Table_Setup> (4\20\7\10) 

<Table_Heads>(\<SPAN>(3)String Descriptor Fields<RULE>) 

<Table_Heads>(String Type\Class\Length\Pointer) 


<Table_Unit> 

<Table_Unit_Heads>(<SPAN>(4\LEFT) Input Argument to Procedures) 
<Table_Row>(Input string passed by descriptor\Read\Read\Read) 
<Endtable_Unit> 


<Table_Unit> 

<Table_Unit_Heads>(<SPAN>(4\LEFT) Output Argument from Procedures; 

Called Procedure Assumes the Descriptor Class) 

<Table_Row>(Output string passed by descriptor, 
fixed-length\Ignored\Read\Read) 

<Table_Row>(Qutput string passed by descriptor, dynamic\Ignored\Read, may be 
modified\Read, may be modified) 

<Endtable_Unit> 
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<TABLE_UNIT> 


<Table_Unit> 
<Table_Unit_Heads>(<SPAN>(4)Output Argument from Procedures, Calling Program 
Specifies the Descriptor Class in the Descriptor) 

<Table_Row>(Output string, fixed-length ---DSC$K_CLASS = S, Z, A, NCA, SD 
\Read\Read\Read) 

<Table_Row>(Output string, dynamic ---DSC$K_CLASS_D 

\Read\Read, may be modified\Read, may be modified) 

<Table_Row>(Output string, varying-length ---DSC$K_CLASS_VS 

\Read\MAXSTRLEN is read; CURLEN is modified\Read) 

<Endtable_Unit> 


<Endtable> 


This example produces the following output: 


Table x — x String Passing Techniques Used by the Run-Time Library 
String Descriptor Fields 


String Type Class Length Pointer 
Input Argument to Procedures 

Input string passed by Read Read Read 
descriptor 


Output Argument from Procedures; Called Procedure Assumes the Descriptor Class 


Output string passed by Ignored Read Read 

descriptor, fixed-length 

Output string passed by Ignored Read, may be Read, may be modified 
descriptor, dynamic modified 


Output Argument from Procedures, Calling Program Specifies the Descriptor Class in the Descriptor 


Output string, fixed-length Read Read Read 
—DSC$K_CLASS = §S, Z, 
A, NCA, SD 
Output string, dynamic Read Read, may be Read, may be modified 
—DSC$K_CLASS_D modified 
Output string, varying- Read MAXSTRLEN Read 
length —DSC$K_CLASS_ is read; 
VS CURLEN is 
modified 
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<TABLE_UNIT_HEADS> 





<TABLE_UNIT_HEADS> 


Specifies headings to be used for a table unit. 





FORMAT 


<TABLE_UNIT_HEADS> (col-heading 
[ \ col-heading...]) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


col-heading 

Specifies the text for the heading for each column; the first argument is 
the heading for the first column. Up to nine arguments can be specified, 
depending on the number of columns in the table. 





© =< TABLE_UNIT> 
: <SPAN> 


° <RULE> 





Can be used only within the context of a table unit established with the 
<TABLE_UNIT> tag. 


Must immediately follow the <TABLE_UNIT> tag. 





None. 


DESCRIPTION 





The <TABLE_UNIT_HEADS> tag specifies column headings for each column 
of the table. The number of column headings depends on the number of 
columns in the table, as determined by the tag <TABLE_SETUP> . 


Often, the heading for a table unit is used to supply a single heading that 
spans the columns of the table and serves to label the table unit, rather than 
the individual columns. In this case, an argument is supplied that begins with 
the <SPAN> tag. 


A null argument leaves the corresponding table column blank. 


ogee é fs 
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<TABLE_UNIT_HEADS> 


Notice that more than one <TABLE_UNIT_HEADS> tag can be supplied 
following a <TABLE_UNIT> tag. When the heading text for a table column 
requires multiple lines, you can do the following: 


e Supply the text as a long argument to a single <TABLE_UNIT_HEADS> 
tag. The text is automatically displayed on the required number of lines. 


e Supply the text of the heading as shorter arguments to successive 
<TABLE_UNIT_HEADS> tags. In this way, you can control how the 
text is displayed on successive lines of the heading. 


If a page break occurs in the table unit, all lines of the table unit heading are 
repeated at the top of the next page. 





EXAMPLE 
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See the example in the description of the <TABLE_UNIT> tag. 


<TAG> 


<TAG> 


Labels a tag. 





FORMAT <TAG> (tag-name | \ tag-arg [\ tag-arg]]) 





ARGUMENTS _ tag-name 


Specifies the name of the tag. 











tag-arg 

Specifies arguments to the tag. 
related tags ° = <LITERAL> 
restrictions Invalid in math. 
required None. 
terminator 





DESCRIPTION The <tTAc> places angle brackets (<...>) around any text and 
optionally creates an argument for the specified tag. For example, when 
<TAG> (newtag\new_argument) is placed in a SDML file it produces 
<NEWTAG> (new_argument) in the output but is not evaluated as a tag. 





EXAMPLES 


<P>You use the <TAG>(p) tag to begin a new paragraph. 


This example may produce the following output: 
eae 


You use the <P> tag to begin a new paragraph. 


LD) 


Use <TAG>(code_example\WIDE) if your example 
has long lines. 


This example may produce the following output: 


Use <CODE_EXAMPLE> (WIDE) if your example has long lines. 


|G) 


A writer can use the <tag>(line_art) tag to label a rough sketch. A writer 
should not use the <literal><icon><endliteral> tag for that purpose. 


This example shows the difference in output caused by <TAG> and 
<LITERAL> : A writer can use the <LINE_ART> tag to label a rough sketch. 
A writer should not use the <icon> tag for that purpose. 
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<TITLE> 


<TITLE> 


Labels the title used on either a title page or part page. 





FORMAT 


<TITLE> (text) 





ARGUMENTS 


related tags 
restrictions 


required 
terminator 


text 
Specifies the text of the title. 





° <TITLE_PAGE> 


® <PART_PAGE> 





May only be used in the context of a <PART_PAGE> tag. 
Must be preceded by <TITLE_PAGE> . 





None. 





DESCRIPTION The <TITLE> tag labels the title used on either a title page or part page. 





EXAMPLE 


See the example in the <PART_PAGE> tag description. 


<TITLE_PAGE> 


<TITLE_PAGE> 


Labels the beginning of a title page and enables the title page tags. 





FORMAT <TITLE_PAGE> 





ARGUMENTS None. 





related tags None. 





restrictions This tag must be used in the context of a <FRONT_MATTER> tag. 


If you are using a preface, the title page must be terminated before the 
<PREFACE> tag. | 





required <ENDTITLE_PAGE> 
terminator 





DESCRIPTION The following title page tags are enabled by the <TITLE_PAGE> tag: 
°  <TITLE> 
¢ — <ORDER_NUMBER> 
© <ABSTRACT> 


° <REVISION_INFO> 





EXAMPLE See the example in the <FRONT_MATTER> tag description. 
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<U> 


Labels the user portion of a dialog between user and system in an 
interactive example. 





FORMAT 


<U> (text) 





ARGUMENTS 


related tags 


text 
Specifies the text of the user input. 





. <INTERACTIVE> 














e <s> 

restrictions None. 

required None. 

terminator 

DESCRIPTION The <u> tag labels the user portion of a dialog between the system and 
a user. An example containing this type of dialog needs to have both parts 
identified in order to differentiate the two types of text in the source code, the 
output, or both. 
The <U> and <S> tags are also used to differentiate the system and user 
text inside of examples created with the <EXAMPLE_SEQUENCE> and <EXI> 
tags, in the Software Doctype. For more information on this doctype, refer to 
the VAX DOCUMENT User Manual, Volume 2. 

EXAMPLES 


<P>The following example of VAXMAIL contains messages from both 


the system and a user of the system: 


<INTERACTIVE> 
<U> (mail) 
<S>(MAIL> )<U>(send) 


<S>(To: )<U>(nodename: : Courtney) 
<S>(%MAIL-E-NOSUCHUSR, no such user COURTNEY at node NODENAME) 


<ENDINTERACTIVE> 


<U> 


This example may produce the following output: 


The following example of VAXMAIL contains messages from both the system 
and a user of the system: 


mail 

MAIL> send 

To: nodename: :Courtney 

YMAIL-E-NOSUCHUSR, no such user COURTNEY at node NODENAME 


For another example, see the example in the discussion of the 
<INTERACTIVE> tag. 
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By pe TPN) ) 
op 


Marks a portion of text to be underlined. 


<UNDERLINE> 


<UNDERLINE> 





FORMAT <UNDERLINE> (text) 
or 


<UNDERLINE> 
text 


<ENDUNDERLINE> 





ARGUMENTS text 


Specifies the text string to be underlined. 





related tags None. 





restrictions Because the text string that is marked for underlining will be kept on the 
same line in the output, do not make the underline longer than the page 
width or errors might be generated. 





required <ENDUNDERLINE> — Required if the text is not passed as an argument. 
terminator 


EXAMPLE 


<P>If you use the appropriate flags, your output 

may look like this: 

<P> 

<SAMPLE_TEXT> 

<UNDERLINE> (The Decline and Fall of the Roman Empire) 
<ENDSAMPLE_TEXT> 





This example may produce the following output: 
If you use the appropriate flags, your output may look like this: 


The Decline and Fall of the Roman Empire 
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<UPDATE_RANGE> 


<UPDATE—RANGE> 


Marks the location at which a new section of updated pages begins. 





FORMAT 


<UPDATE—_RANGE> (start-page \ end-page) 





ARGUMENTS 


related tags | 


restrictions 


required 
terminator 


start-page 
Specifies the page number from the printed documentation of the first page 
that must be printed. This must be an odd-numbered page. 


end-page 

Specifies either the last page to be included in a set of update pages or 
the keyword EOF. If end-page is a number, that number must be an 

even number. The text formatter output routines that handle updates will 
automatically generate point-numbered pages if text within the bounds of 
start-page and end-page will not fit within those pages. If EOF is specified, 
then the update range continues to the end of a chapter or section. 





. <REVISION> 


bd <MARK> 





Must be used in the context of the <REVISION> tag, and <REVISION> must 
specify the keyword UPDATE. If the <REVISION> tag is not specified, then 
the <UPDATE_RANGE> and <ENDUPDATE_RANGE> tags are nonoperational; 
that is, no output will be generated from these tags when the file is processed. 





<ENDUPDATE_RANGE> 


DESCRIPTION Files coded with the <REVISION> (UPDATE\update-level) tag and containing 


<UPDATE_RANGE> tags will process as follows: 


When the text formatter processes a file that has been marked as an 
update, it processes all text and commands in the file, but does not 
produce actual output for the DVI file except for those pages marked 
within an update range. 


When the text formatter reaches the beginning of an update range, it 
sets the page number to the page number specified as the start of the 
update. Therefore, it is not important that previous versions of the text 
formatter file were modified for pagination during final production. All 
pages processed outside of an update range are not output. 
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<UPDATE_RANGE> 
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The following rules apply to the placement of the <UPDATE_RANGE> tag: 


e If the text on the first update page is in the middle of a text element 
(for example, a paragraph, a list element, a code example), then the 
<UPDATE_RANGE> tag must precede the word of text that is the first 
word on the page. 


e If the text on the first update page represents the beginning of a new text 
element (<P>, <LIST>, <LE>, <CODE_EXAMPLE> , and so on), the 
<UPDATE_RANGE> tag must be placed immediately preceding the tag for 
the text element. 


e If an update range begins on a page that starts with a continued table, 
the file must specify the start of the update range on the odd-numbered 
page preceding the beginning of that table, or (if the table begins on an 
odd-numbered page) the page on which the table begins. If these pages 
are not to be a part of the update, they may be discarded. 


e If one or more pages before an update range begins contains 
a floating figure or example, the <FIGURE_ATTRIBUTES> or 
<EXAMPLE_ATTRIBUTES> tags must be modified to specify KEEP. This 
will prevent the text formatter from floating the figure or example to the 
top of the first update page. 


Put a <COMMENT> tag in the file to indicate that the modification was 
made for the purposes of the update only. For example: 


<COMMENT>(KEEP added to example for update only...) 


When the file is subsequently revised, the KEEP arguments can be 
removed. 


e When a file that contains the <REVISION> (UPDATE)-tag is processed, the 
table of contents and index are handled as follows: 


e If the <CONTENTS_FILE> or <INDEX_FILE> tag occurs between 
the bounds of <UPDATE_RANGE> and <ENDUPDATE_RANGE> , and 
/CONTENTS or /INDEX is specified on the command line, the 
contents file or index file is included within the pages for the update 
range. 


e If the <CONTENTS_FILE> or <INDEX—FILE> tag occurs in the file 
but is specified outside the bounds of <UPDATE_RANGE> and 
<ENDUPDATE_RANGE> tags, and if /CONTENTS or /INDEX is 
~ specified on the command line, the table of contents file or index file 
is included in the output file. 


<UPDATE—_RANGE> 





EXAMPLE 


<REVISION>(UPDATE\July 1986) 


<UPDATE_RANGE> (5\24) 
<P> 
The first sentence on page 5 goes here. 


20 or more pages of modified text goes here. 


The last sentence on page 24.n goes here. 
<ENDUPDATE_RANGE> 


In this example, the updated material begins on page 5 and continues through 
page 24. When page 24 is reached, the page numbering becomes 24.1, 24.2, 
etc., until the end of the update range is reached. The <ENDUPDATE_RANGE> 
tag must be placed in the source file at the position corresponding to the place 
at which an update sequence ends. 
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<UPPERCASE> 


<UPPERCASE> 


Labels text that should appear as uppercase in the final output. 





FORMAT 


<UPPERCASE > (text) 





ARGUMENTS 


related tags 


text 


Specifies the text to appear in uppercase. 





» <LOWERCASE> 





None. 











restrictions 

required None. 

terminator 

DESCRIPTION _If your book contains a text element, such as a heading, that normally appears 
in lowercase, you may encounter a situation where you need to overcome the 
default case in one of your tags and ensure that the result in the final output 
appears in uppercase. The <UPPERCASE> tag allows you to do this. 

EXAMPLE 


<HEAD2>(here is an example of UPPERCASE text) 


In this example, assume that the doctype being used causes the tag <HEAD2> 
to output a heading that is in lowercase, no matter what the case of the text 
passed to it. The <UPPERCASE> tag overrides the default in this <HEAD2> 
tag. This example produces the following output: 


here is an example of UPPERCASE text 


<USER_I_MESSAGE> 





<USER_I_MESSAGE> 


Sends an informational message to the terminal or log file during 
processing of a file. 





FORMAT <USER_I_MESSAGE> (text) 





ARGUMENTS _ text 


Specifies the text you wish to appear on the terminal or in the log file. 





related tags ©  <USER_W_MESSAGE> 





' restrictions You must process the file with the /LOG qualifier in order to see any <USER_ 
I_MESSAGE> messages. 


The message text is limited to 150 characters. 





required None. 
terminator 





DESCRIPTION The <USER-I_MESSAGE> tag generates a message when the file is processed, 
but only when the /LOG qualifier is specified on the command line. The 
message is sent to the terminal if the file is processed interactively or to the 
log file if it is processed as a batch job. 


The messages are listed in the .LIS file if you specify the /LIST qualifier on 
the command line. | - 


You can use the tag to broadcast any important information that should be 
noted or flagged during tag translation; for example, you might use it as a 
reminder that a part of the file is incomplete. 


The tag translator displays the line number and the file name in which the 
tag appears. The message is output in the following format: 


¥%TAG-I-USER_IMSG, mmmmmmmmmmmmmmmmmm 
Line is nnn of file fffffffffffff 


Note: To receive any messages tagged with <USER_I_MESSAGE> tags, you must 
process the file with the /LOG qualifier on the command line. If you 
want to generate only a few messages, you might choose to use the 

<USER_W_MESSAGE> tag and not process the file with the additional 
qualifier. 
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<USER_I_MESSAGE> 





EXAMPLE 


<USER_I_MESSAGE>(Section 2 is incomplete and requires 
information from Tom Jones.) 


This example shows how a <USER_I_MESSAGE> tag can be used to flag a 
section of a file that requires further work. The message would only be sent 
to the terminal if the user processed the file with the /LOG qualifier on the 
command line. If the text element containing this tag were processed as a 
batch job, the log file would contain the following entry: 


“TAG-I-USER_IMSG, Section 2 is incomplete and requires information 


from Tom Jones. 
Line is 68 of file part2.gnc 


9-242 


<USER_W_MESSAGE> 


<USER_W_MESSAGE> 


Sends a warning message to the terminal or log file during processing of a 
file. 





FORMAT 


<USER_W_MESSAGE> (warning-text) 





iv] 


ARGUMENTS 


related tags 
restrictions 


required 
terminator 


warning-text 
The text you wish to appear on the terminal or in the log file. 





° <USER_I_MESSAGE> 





The message text is limited to 150 characters. 





None. 


DESCRIPTION 


Note: 


The <USER_W_MESSAGE> tag generates a message when the file is processed, 
sending it to the terminal if processed interactively or to the log file if 
processed as a batch job. 


This type of message is counted by the tag translator as a warning 
message. After thirty warning messages, tag translation halts. Therefore, 
use the <USER_W_MESSAGE> tag for generating messages only if you 

are issuing few messages. For a file that contains many messages, tag 
messages with <USER_I_MESSAGE> tags and process the file with the 
/LOG qualifier. 


You can use it to flag any important information that should be noted during 
processing; for example, you might use it as a reminder that a part of the file 
is incomplete. Whatever message you enter as an argument to the <USER_W_ 
MESSAGE> tag is written to the terminal or to the batch log file when the text 
element that contains it is processed through the tag translator. 


The tag translator displays the line number and the file name in which the 
<USER_W_MESSAGE> tag appears. The message is output in the following 
format: 


%TAG-W-USER_WMSG, at tag <USER_W_MESSAGE> on line nnn of file 
ffffffff 
MMIMMMMMMMMMMMMMMMMMMMmmmmmmm 


The messages are listed in the .LIS file if you specify the /LIST qualifier on 
the command line. 
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<USER_W_MESSAGE> 





EXAMPLE 


<USER_W_MESSAGE> (Reviewers: Please note missing parameters here.) 


This example shows how the <USER_W_MESSAGE> tag is used to identify 
a notice in a file. If the file containing this message was called “Reviewers_ 
copy.SDML,” and it was processed as a batch job, the log file would contain 
the following entry: | 


%TAG-W-USER_WMSG, at tag USER_W_MESSAGE on line nn of file 


Reviewers_copy.SDML. 
Reviewers: Please note missing parameters here. 
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<VALID_BREAK> 





<VALID_BREAK> 


Labels a permissible page break within a monospaced example. 





FORMAT <VALID_BREAK> 





ARGUMENTS None. 





related tags © — <CODE_EXAMPLE> 
®  <INTERACTIVE> 





restrictions This tag can be used only within monospaced examples such as <CODE_ 
EXAMPLE> or <DISPLAY> . 





required None. 
terminator 





DESCRIPTION The text formatter attempts to keep an example together on a single page. 
If there isn’t enough room for an example on the current page, the text 
formatter chooses page breaks using blank lines in the example as “good” 
places to break. If your example contains no blank lines, or if you want to 
specify better breaking points, you can use <VALID_BREAK> to specify the 
places that are ’"good” page breaks. 





EXAMPLE 


<CODE_EXAMPLE> 
<S>($) 
<U> (@SYS$SYSTEM : SHUTDOWN) 


<S>( SHUTDOWN -- Perform an Orderly System Shutdown) 
<ELLIPSIS> 

<S>(CENTRAL, PRINTER, TAPES, DISKS, DEVICES, CARDS, NETWORK, OPER1) 
<S>(OPER3, OPER4, OPERS, OPER6, OPER7, OPERS8, OPER9, OPER10, OPER11,) 
<S>(OPER12) 

<VALID_BREAK> 


<S>(/%SHUTDOWN-I-DISLOGINS, Interactive logins will now be disabled.) 
<S>(/SET-I-INTSET, login interactive limit = 0 current interactive value = 17) 
<S> (%SHUTDOWN-I-SHUTNET, The DECnet network will now be shut down.) 
<S>(%,SHUTDOWN-I-STOPQUEMAN, The queue manager will now be stopped.) 


<S> (SHUTDOWN message on AVALON, from user SYSTEM at _AVALON$OPAO: 12:04:00.20) 
<S>(AVALON will shut down in 5 minutes; back up 12:30. Please log off node AVALON.) 
<S>(MONTHLY PREVENTIVE MAINTENANCE) 


<S>(17 terminals have been notified on AVALON.) 


<VALID_BREAK> 


<S>(hhhhhhhhhkh OPCOM, 16-JUN-1984 12:05:12.30 %nnnMMMMM) 
<S>(Message from user DECnet on AVALON) 

<S>(DECnet event 2.0, local node state change) 

<S>(From node 2.161 (AVALON), 16-JUN-1984 12:05:22.26) 
<S>(Operator command, Old state = On, New state = Shut) 


<S>(SHUTDOWN message on AVALON from user SYSTEM at _AVALON$OPAO: 12:07:12.56) 
<S>(AVALON will shut down in 3 minutes; back up 12:30. Please log off node AVALON.) 
<S>(MONTHLY PREVENTIVE MAINTENANCE) 


<S>(%,SHUTDOWN-I-STOPQUEMAN, The queue manager will now be stopped.) 

<S>(SHUTDOWN message on AVALON user SYSTEM at _AVALON$OPAO: 12:07:12.56) 
<S>(AVALON will shut down in 3 minutes; back up 12:30. Please log off node AVALON.) 
<S>(MONTHLY PREVENTIVE MAINTENANCE) 

<VALID_BREAK> 


<S>(hhhhhhhhhhh OPCOM, 16-JUN-1984 12:08:12:30 %NALLLLhLb) 
<S>(Message from user JOB_CONTROL on AVALON -SYSTEM-S-NORMAL, normal 
successful completion) 


<S> CUE heheh OPCOM ’ 16-JUN- 1984 12 7 08 = 42 . 30 Ihollleltelotolele) 
<S>(Message from user DECNET on AVALON DECnet shutting down) 


<S>(SHUTDOWN message on AVALON from user SYSTEM at _AVALON$OPAO: 12:09:12.56) 
<S>(AVALON will shut down in 1 minute; back up 12:30. Please log off node AVALON.) 
<S>(MONTHLY PREVENTIVE MAINTENANCE) 


<S>(17 terminals have been notified on AVALON) 

<S>(,SHUTDOWN-I-SITESHUT, The site-specific shutdown procedure 
will now be invoked.) 

<S>(/Z,SHUTDOWN-I-STOPUSER, All user processes will now be stopped.) 

<S>(%,SHUTDOWN-I-REMOVE, All installed images will now be removed.) 

<S>(%,SHUTDOWN-I-DISMOUNT, All volumes will now be dismounted.) 

<S>(hhhhhhhhhhh OPCOM, 16-JUN-1984 12:09:42.30 “UhALALAbA) 

<S>(Message from user System on AVALON 

_AVALON$OPAO:, AVALON shutdown was requested by the operator.) 


<S>(Ukhhhhhhhhh OPCOM, 16-JUN-1984 12:10:02.44 %LAKALLALL) 
<S>(Logfile was closed by operator _AVALON$OPAO: 
Logfile was SYS$SYSROOT: [SYSMGR] OPERATOR. LOG; 8) 


<S>(KhhMhhhhhhh OPCOM, 16-JUN-1984 12:10:32.20 “ULLAL 
<S>(Operator _AVALON$OPAO: has been disabled, username SYSTEM) 


<S>( SYSTEM SHUTDOWN COMPLETE - USE CONSOLE TO HALT SYSTEM) 
<ENDCODE_EXAMPLE> 


This example may produce the following output: 


$ @SYS$SYSTEM : SHUTDOWN 


SHUTDOWN -- Perform an Orderly System Shutdown 


CENTRAL, PRINTER, TAPES, DISKS, DEVICES, CARDS, NETWORK, OPER1 
OPER3, OPER4, OPERS, OPER6, OPER7, OPERS, OPER9, OPER10, OPERi1, 
OPER12 


“%SHUTDOWN-I-DISLOGINS, Interactive logins will now be disabled. 
%SET-I-INTSET, login interactive limit = 0 current interactive value = 17 
%SHUTDOWN-I-SHUTNET, The DECnet network will now be shut down. 
“SHUTDOWN-I-STOPQUEMAN, The queue manager will now be stopped. 


SHUTDOWN message on AVALON, from user SYSTEM at _AVALON$OPAO: 12:04:00.20 
AVALON will shut down in 5 minutes; back up 12:30. Please log off node AVALON. 
MONTHLY PREVENTIVE MAINTENANCE 


17 terminals have been notified on AVALON. 
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<VALID_BREAK> 


hhhhhhhhhhh OPCOM, 16-JUN-1984 12:05:12.30 %unhhhhhhhd 
Message from user DECnet on AVALON 

DECnet event 2.0, local node state change 

From node 2.161 (AVALON), 16-JUN-1984 12:05:22.26 
Operator command, Old state = On, New state = Shut 


SHUTDOWN message on AVALON from user SYSTEM at _AVALON$OPAO: 12:07:12.56 
AVALON will shut down in 3 minutes; back up 12:30. Please log off node AVALON. 
MONTHLY PREVENTIVE MAINTENANCE 


“%SHUTDOWN-I-STOPQUEMAN, The queue manager will now be stopped. 

SHUTDOWN message on AVALON user SYSTEM at _AVALON$OPAO: 12:07:12.56 

AVALON will shut down in 3 minutes; back up 12:30. Please log off node AVALON. 
MONTHLY PREVENTIVE MAINTENANCE 


Whkhhbhhhhh OPCOM, 16-JUN-1984 12:08:12:30 %AAMMLL 
Message from user JOB_CONTROL on AVALON 
-SYSTEM-S-NORMAL, normal successful completion 


hhhhkhhhhhh OPCOM, 16-JUN-1984 12:08:42.30 Ahn Lhhhh 
Message from user DECNET on AVALON 
DECnet shutting down 


SHUTDOWN message on AVALON from user SYSTEM at _AVALON$OPAO: 12:09:12.56 
AVALON will shut down in 1 minute; back up 12:30. Please log off node AVALON. 
MONTHLY PREVENTIVE MAINTENANCE 


17 terminals have been notified on AVALON 

“%SHUTDOWN-I-SITESHUT, The site-specific shutdown procedure will now be invoked. 
%SHUTDOWN-I-STOPUSER, All user processes will now be stopped. 
%SHUTDOWN-I-REMOVE, All installed images will now be removed. 
%SHUTDOWN-I-DISMOUNT, All volumes will now be dismounted. 

hhhhhhhhhhh OPCOM, 16-JUN-1984 12:09:42.30 %AnMmhbhbhh 

Message from user System on AVALON 

_AVALONSOPAO:, AVALON shutdown was requested by the operator. 


hhhhhhhbhh OPCOM, 16-JUN-1984 12:10:02.44 “uhhhhhhhhh 
Logfile was closed by operator _AVALON$OPAO: 
Logfile was SYS$SYSROOT: [SYSMGR] OPERATOR .LOG; 8 


WEEN, =«OPCOM, 16-JUN-1984 12:10:32.20 Y%URRLKLWLL% 
Operator _AVALON$OPAO: has been disabled, username SYSTEM 


SYSTEM SHUTDOWN COMPLETE - USE CONSOLE TO HALT SYSTEM 


9-247 


<VALID_TABLE_ROW_BREAK> 


<VALID_TABLE_ROW_BREAK> 


Marks a permissible place that a first-level table row may be broken across 
pages. 





FORMAT <VALID_TABLE_ROW_BREAK> 





ARGUMENTS = None. 





related tags e  <NESTED_TABLE_BREAK> 





restrictions This tag must be used in the context of a table. May only be used in the last 
column of a 2- or 3-column, first-level table. That is, this tag may not be 
specified in a table that is specified inside a <TABLE_ROW> tag. 





required None. 
terminator 





DESCRIPTION The <VALID_TABLE_ROW_BREAK> tag provides an allowable place for 
; a long table column to be broken across a page. If you do not use the 
<VALID_TABLE_ROW_BREAK> tag inside a long table row, the text formatter 
tries to keep all the text on the same page of output and might issue a PAGE- 
TOO-LONG error message. In extreme cases, the text formatter could run out 
of memory trying to process the table row and terminate processing. 


You should use it before another nested formatting tag, or aftera <P> tag. 


EXAMPLE 


<TABLE> 

<TABLE_ATTRIBUTES> (MULTIPAGE) 

<TABLE_SETUP> (2\9) 

<TABLE_ROW>(Item\Text that goes on for several paragraphs. 
<VALID_TABLE_ROW_BREAK> 

Text that is still inside the first table row. 

<P> 

<VALID_TABLE_ROW_BREAK> 

The last paragraphs for this table row.) 

<ENDTABLE> 


This example shows the use of the <VALID.TABLE_ROW_BREAK> tag in a table 
with a long row. 


<VARIABLE> 


<VARIABLE> 


Labels a program variable or number. 





FORMAT <VARIABLE> (variable-name) 





ARGUMENTS _ variable-name 


Specifies the name of the variable to be typographically distinguished. 











related tags ¢ — <KEYWORD> 
restrictions None. 
required None. 
terminator 





DESCRIPTION The <vVARIABLE> tag names a variable discussed in text. Use of the 
<VARIABLE> tag and its result in formatted text must be agreed upon by 
writer, editor, and book designer. Above all, you should seek a consistent 
usage within a document and across a document set. 





EXAMPLE 


<P>At this point in the processing, 
<VARIABLE> (NUMBER_OF_JELLYBEANS) has the 
value 

of 2. 


This example may produce the following output: 


At this point in the processing, NUMBER—OF_JELLYBEANS has the value 
of 2. 
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<VBAR> 


<VBAR> 


Labels an occurrence of a vertical bar in an argument to a tag. 





FORMAT <VBAR> 





ARGUMENTS = Nore. 











related tags e The following tags label other characters that must be tagged when they 
. occur in an argument to a global tag: 
<AMPERSAND> 
<BACKSLASH> 
<CPAREN> 
<OPAREN> 
restrictions Can only be used within an argument to a tag. 
required None. 
terminator 





DESCRIPTION The tag translator uses a vertical bar (|) to begin a quoted string. An 
ampersand concludes a quoted string. If you use a literal vertical bar within 
an argument to an SDML tag, the tag translator reads the vertical bar as 
beginning a section of text it should treat literally. The vertical bar may 
prevent the tag translator from evaluating a tag when it should and may 
cause an error in your output. 


To process a vertical bar in an argument to a tag (through to your output), 
use the <VBAR> tag. 





EXAMPLE 


<SUBHEAD1>(Labeling the Vertical Bar (<VBAR>) Within Your 
Code) 

<P>To pass a vertical bar (|) in an argument to a tag through 
to your output, 


This example produces the following output: 


Labeling the Vertical Bar (|) Within Your Code 


To pass a vertical bar (|) in an argument to a tag through to your output, ... 


<X> 





<X> 


Creates an index entry with a reference to the page on which this tag 
appears. 





FORMAT 


<X> (index-entry| \ attribute) 





ARGUMENTS 


index-entry 
Specifies the index entry to appear in the index. The capitalization you use in 
this string will be the capitalization that appears in the index. 


Use the <XSUBENTRY> tag to separate the main entry from the first subentry, 
if used, and the second subentry from the first, as follows: 


<x> (main entry <xsuBeNTRY> subentry) 


You should use no more than two levels of subentries in a book index. 


attribute 

Specifies the attributes that control the sorting and formatting of the index 
entry. You can specify a maximum of five attribute arguments from among 
the following possibilities. Each attribute must be passed as a separate 
argument. 





Attribute Function 


<XAPPEND> (string) Causes the indexing software to append the specified 
string to the page reference in the index. 


BEGIN Causes the indexing program to begin a page-range 
reference. When you use this attribute, you must pair it 
with a following <X> _ tag that has identical text and the 
END attribute. 


BOLD Causes the page reference number to appear in boldface. 
; This is distinct from any boldfacing that appears in the 
text of the index entry itself. 


END Causes the index program to end a page-range reference. 
When you use this attribute, you must pair it with a 
previous <X> _ tag that has identical text and the BEGIN 
attribute. 


ITALIC Causes page reference numbers to appear in italic type in 
your index entry. If both BOLD and ITALIC are specified, 
the entry is output in bold italic type. Entries that use the 
ITALIC attribute are sorted as being distinct from entries 
that are output in an italic type face using some other 
means (such as the global <EMPHASIS> tag). 
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<X> 


related tags 


restrictions 


required 
terminator 


Attribute Function 
MASTER Causes the index program to insert the entry only in the 


master index. By default, the entries are inserted only 
in the local index. This attribute allows you to specify 
different entries for a book’s local index and for the 
master index of the document set. 


<XSORT> (string) Causes the index program to use the specified string as 
the sort key when placing this entry in the index. Use 
this attribute to override the sorting algorithm of the index 
utility for single index entries (for example, to force an 
entry with a leading nonalphanumeric character to the top 
of the index). 





e <yY>-—Used for entering a cross-reference index entry 





Do not place <x> tags within any kind of example. Doing so will interfere 
with the formatting of the examples. 


Be sure <X> tags follow headings, commands, and other major text elements 
that are likely to begin a new page. 


<X> tags that indicate items in tables must be placed inside the <TABLE_ 
ROW> tags. 








DESCRIPTION 
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The <X> tag creates an entry in the index to the book. The entry that 
appears in the index is composed of the main entry and subentries (if any) 
specified in the first argument to the tag. 


You can control how the index entry is sorted and how it appears by 
specifying particular attributes in arguments two through six of the <x> 


tag. 


For instance, the <XAPPEND> attribute is useful for marking an index page 
reference as referring to an example (5-4ex) or to a table (9-8tab). The 
<XAPPEND> attribute can also be used for such common indexing terms as 
“page 3ff” or “5-3 to 5-6 passim.” 


The appended string is boldfaced or italicized if its page reference is boldfaced 
or italicized. BOLD and ITALIC can be used together. 


You can create an index entry for several inclusive pages by using the BEGIN | 
and END attributes. When using a BEGIN and END pair, you must be certain 
that the index entries are identical and that any other attributes you specify 
are the same for each entry, as well. 


You can specify that an index entry appear in a master index by using the 
MASTER attribute. By default, an entry appears in the master index only if 
this attribute has been specified. It is possible to override this arrangement at 
the time the master index is built and include every entry in the local index in 
the master. No entry marked with the MASTER attribute appears in the local 
index. 


<X> 


If you have an index entry for which you want to control the sorting, you 
can do so by using the <XxSORT> attribute. For example, since leading 
nonalphabetic characters are ignored by default, the main entry $SEARCH 
normally appears with other entries beginning with the letter “S.” To force 
the indexing software to place $SEARCH before ne “A” section, use the 
<XSORT> attribute as follows: 


<X> ($SEARCH\<XSORT> ($) ) 


You must use the <XSORT> attribute if your main entry begins with a double 
backslash or a right angle bracket. 


The <XSUBENTRY> Tag 


You can use the <XSUBENTRY> tag within this argument to separate the 
main entry from the first subentry, and the second subentry from the first, as 
follows: 


<X> (Main entry <xsubentry> subentry-1 <xsubentry> subentry-2) 


The <XSUBENTRY> tag can be abbreviated as <xS>. Using this shorter form 
of the tag, the previous example could be expressed as follows: 


<X> (Main entry <xs> subentry-1 <xs> subentry-2) 


You can use no more than three levels of subentries in an index. 





EXAMPLES 


<X>(File structure\begin) 


<X>(File structure\end) 


These index commands create an inclusive page entry, and may produce the 
following output. 


File structure, 5-4 to 5-7 


<X>(File structure\begin) 


<X>(File structure\end\<XAPPEND>( passim) ) 


This index command creates an index entry like the following: 


File structure, 5-4 to 5-7 passim 
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<Y> 





<Y> 


Creates an index entry with no reference to the page on which this tag 
appears. Used for cross-references ("See” or “See also” entries). 





FORMAT. 


<Y> (index-entry/ \ attribute]) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


9-254 


index-entry 

Specifies the string that supplies additional information to the main entry and 
subentries that will appear in the index. The capitalization you use in this 
string will be the capitalization that appears in the index. 


Use the <XSUBENTRY> tag to separate the main entry from the first subentry, 
and the second subentry from the first, as follows: 


Main entry <xsubentry> subentry 
You should use no more than two levels of subentries in a book index. 


attribute 


Specifies the attributes that control the sorting and formatting of the index 
entry. You can specify a maximum of two attribute arguments from among 
the following possibilities. Each attribute must be passed as a separate 
argument. 


Attribute Function 
MASTER Causes the index program to insert the entry only in the 


master index. By default, the entry is inserted only in the 
local index. This attribute allows you to specify different 
entries for a book’s local index and for the master index of 
the document set. 


<XSORT > (string) Causes the index program to use the specified string as the 
sort key when placing this entry in the index. You must 
enclose the string in either double quotation marks (“) or 
single quotation marks (’). Use this attribute to override the 
sorting algorithm of the index utility for single index entries. 





<X> 





Do not place <Y> tags within any kind of example. Doing so will interfere 
with the formatting of the examples. 





None. 


<Y> 





DESCRIPTION The <y> tag creates an unpaged entry in the index to the book. The entry 
that appears in the index is composed of the main entry and “See” or “See 
also” subentries specified in the first argument to the tag. 


You can control how the index entry is sorted and where it will appear by © 
specifying particular attributes in arguments two through four of the <yY> 
tag. 


You can specify that an index entry appear in a master index by using the 
MASTER attribute. By default, an entry will appear in the master index only 
if this attribute has been specified. It is possible to override this arrangement 
and include every entry in the local index in the master. 


If you have an index entry for which you want to control the sorting, you 
can do so by using the <XSORT> attribute. For example, because leading 
nonalphabetic characters are ignored by default, the main entry $SEARCH 
normally appears with other entries beginning with the letter “S.” To force 
the indexing software to place $SEARCH before the “A” section, you can use 
the SORT attribute as follows: 


<Y> ($SEARCH <XS> See System Services\ <XSORT> ($)) 





EXAMPLE 


<X>(File structure designators) 
<Y>(File structure designators<XSUBENTRY>See also Header blocks) 


This index command would create the following index entry, assuming these 
tags appeared on page 1-3: 


File stucture designators, 1-3 
See also Header blocks 
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AA = VAXDOCUMENT Command Summary 


This appendix describes the DCL command line interface to 
VAX DOCUMENT. A summary of this information can be obtained by 
typing the following command once VAX DOCUMENT is installed: 


$ HELP DOCUMENT 


See Chapter 4 for tutorial information on how to process your files using the 
DOCUMENT command. 
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‘DOCUMENT 


DOCUMENT 


Invokes the VAX DOCUMENT document production system. 








FORMAT DOCUMENT input-file-spec doctype destination 
Command Qualifier Default 
/[NO]JBA TCH|=qualifier-keyword] /NOBATCH 
/CONDITION=condition-name None. 
/[NOJCONTENTS /NOCONTENTS 
/[NOJDEVICE_CONVERTER|=device-keyword] /DEVICE_CONVERTER 
/[NOJDIAGNOSTICS/=file-spec] /NODIAGNOSTICS 
/ELEMENT=file-spec None. 
/INCLUDE=file-spec None. 
/[NOJINDEX[=index-keyword] /NOINDEX 
/[NO]KEEP[=filetype-keyword] _/NOKEEP 
/[NOJLIST /NOLIST 
/[NO]JLOG /LOG 
/[NOJMAPI|=file-spec] /NOMAP 
/MASTER_INDEX None. 
/[NO]PRINT [=qualifier-keyword] /PRINT 
/PROFILE=file-spec None. 
/[NO]SYMBOLS=file-spec /NOSYMBOLS 
/[NO]JTAG_TRANSLA TOR /TAG_TRANSLATOR 
/[NO]TEXT_FORMATTER /TEXT_FORMATTER 
restrictions None. 





PARAMETERS input-file-spec 


Specifies the input file to be processed. Note that wildcards are not allowed 
in the input file specification. 

The default file type of the input file specification expected by 

VAX DOCUMENT is SDML. If qualifiers are specified, VAX DOCUMENT 


determines the default file type based on the qualifiers and the destination 
keyword you specify. 


Table A-1 lists the default file types and the qualifiers and destinations that 
provide them. 


Table A—1_ Default File Types 


VAX DOCUMENT 


Destination 


DOCUMENT 


Default Input 


Qualifiers Used Keyword Used File Type 
None. Any SDML 
/TAG_TRANSLATOR Any SDML 
/NOTAG_TRANSLATOR Any TEX 
/TEXT_FORMATTER 
/NOTAG_TRANSLATOR LNO3_LASER_PRINTER DVI_LNO3 
/NOTEXT_FORMATTER POSTSCRIPT DVI_POST 
/DEVICE_CONVERTER LINE_PRINTER DVI_LINE 
TERMINAL DVI_LINE 
MAIL DVI_LINE 
/NOTAG_TRANSLATOR LNO3_LASER_PRINTER LNO3 
/NOTEXT_FORMATTER POSTSCRIPT POST 
/NODEVICE_CONVERTER LINE_PRINTER LINE 
/PRINT TERMINAL TERM 
MAIL TXT 


‘Braces in this table indicate that the enclosed qualifiers occur together on the 
command line. 


doctype 

Specifies the type of document being produced. The doctype you select on the 
command line determines the style of your output and determines the SDML 
tags you can use. Note that some tags are valid only in specific doctypes. 
See the VAX DOCUMENT User Manual, Volume 2, for more information on 
doctype-specific tags. 


All doctypes have a default design. Some doctypes have several designs. 
These doctypes accept a design keyword as part of the doctype specification. 
The design keyword specifies an alternate design within the doctype. For 
example, the SOFTWARE doctype has designs for different page sizes, 
heading level formats, and so on. 


The design keyword is specified as part of the doctype and is separated from 
the doctype keyword by a period (.). For example, the REPORT doctype 
has two alternate designs: one in which the text runs the full text page 
width (the default), and another in which the text is placed in two columns. 
You specify the default design as REPORT and the two-column design as 
REPORT.TWOCOL. You can abbreviate the doctype keyword to any unique 
string. For example, you could abbreviate REPORT.TWOCOL to REP.TWO, 
or even R.T as long as each keyword is unique. 


Table A-2 summarizes the supported VAX DOCUMENT doctype keywords 
and includes a basic use for each keyword, and a summary description of the 
available designs. See the VAX DOCUMENT Design Samples manual for more 
information on each of these doctype designs. 


DOCUMENT 


Table A-2 VAX DOCUMENT Doctypes 


Doctype Keyword Used to Create 

ARTICLE Articles 

LETTER Letters or memos 

MANUAL.GUIDE User manuals 

MANUAL.PRIMER 

MANUAL.REFERENCE 

MILSPEC Military specifications 

OVERHEADS Overhead slides for 
transparencies 

OVERHEADS.35MM 

REPORT General-purpose 
documents 

REPORT.TWOCOL 

SOFTWARE.BROCHURE User manuals 


containing detailed 
information on software 


SOFTWARE.GUIDE 
SOFTWARE.HANDBOOK 
SOFTWARE.POCKET_REFERENCE 
SOFTWARE.REFERENCE 
SOFTWARE.SPECIFICATION 


Design Description 


83 X 11 inches, numbered or unnumbered 
headings, text is placed in a two-column format 


83 X 11 inches, unnumbered headings 
7 x 9 inches, numbered headings 

7 x 9 inches, unnumbered headings 
84 x 11 inches, numbered headings 
84 x 11 inches, numbered headings 
83 X 11 inches, no headings 


65 x 53 inches, no headings 
83 x 11 inches, numbered headings 


83 x 11 inches, numbered headings, text is 
placed in a two-column format 


7 x 9 inches, unnumbered headings 


7 x 9 inches, numbered headings 

7 x 9 inches, numbered headings 
53 X 7 inches, numbered headings 
85 x 11 inches, numbered headings 
83 x 11 inches, numbered headings 


You can have additional local doctype keywords defined at your site. See 


your VAX DOCUMENT system 


keywords. 


destination 


administrator for information on local doctype 


Specifies the output device destination for the document. VAX DOCUMENT 
supports the following output destination keywords: 


Destination Keyword 
LINE_PRINTER' 
LNO3_LASER_PRINTER' 
POSTSCRIPT' 


Formatted For 
A line printer 
An LNO3 laser printer 


Any Digital-supported POSTSCRIPT” output device, 
such as the PRINTSERVER 40 or the LNO3R 


SCRIPTPRINTER 


TERMINAL 
MAIL 


A standard ANSI terminal, such as the VT-100 — 
Sending through the VMS Mail Utility . 


‘These destinations are installed at your site only if they were selected during the 


installation procedure. 


PostScriet is a registered trademark of Adobe Systems, Inc. 


A-4 


DOCUMENT 


You can abbreviate the destination keyword to any unique string. For 
example, you could abbreviate LNO3_LASER—PRINTER to LNO3, or even 
LN as long as that string is unique. 


You can have additional local destination keywords defined at your site. 
See your VAX DOCUMENT system administrator for information on local 
destination keywords. 


A ee eae a a a eT) 
DESCRIPTION DOCUMENT is the command you specify to invoke VAX DOCUMENT. 


VAX DOCUMENT is a document production system that lets you create 
documents in many different formats for a variety of output devices. All 
documents are created by entering SDML tags into an input file which is then 
processed by VAX DOCUMENT. 


The DOCUMENT command requires three parameters: 
¢ Input File Specification 


Specifies the input file for VAX DOCUMENT. This file is by default an 
SDML file containing SDML tags, however, it can also be one of the 
intermediate files generated by VAX DOCUMENT. 


e Doctype 


Specifies the document type keyword for which the input file should be 
processed. This keyword specifies the kind of document to be created (a 
letter, a software manual, a journal article, and so on). 


e Destination . 


Specifies the final processing destination for the input file. This keyword 
typically specifies a format used by a printer, but can specify formats for 
terminals or the VMS Mail Utility. 


You can use the qualifiers to the DOCUMENT command to create indexes, 
master indexes, tables of contents, and to modify the default processing of 
your input file. 





COMMAND 
QUALIFIERS 


/BATCH[=(qualifier-keyword[, qualifier-keyword...])] 


/NOBATCH 

Specifies whether VAX DOCUMENT should be run interactively or submitted 
as a batch job. The default qualifier is /NOBATCH, which specifies that 
VAX DOCUMENT should be run interactively. 


The /BATCH qualifier builds and issues a DCL SUBMIT command that 
submits a job to SYS$BATCH with a job name that has the same file name 
as the input-file-spec used on the command line, prefixed with the string 
“DOC$.” For example, the file ROUTINES.SDML would be submitted as the 
job DOC$ROUTINES. 


You can use any of the DCL SUBMIT command qualifiers with 
VAX DOCUMENT by passing these qualifiers as keywords to the /BATCH 
qualifier. 


DOCUMENT 


For example, if you want a command procedure to be run after 9:00 and want 
to be notified when it completes, you could use the following command: 


$ SUBMIT somefile.com /AFTER=09 : 00/NOTIFY 


You can specify the same options for your document processing using the 
/BATCH qualifier on the command line as follows: 


$ DOCUMENT somefile /BATCH=(AFTER=09:00,NOTIFY) LETTER LNO3 


When you use the /BATCH qualifier, a file is created in your current default 
directory that contains information about the batch job. This file has the same 
file name as the input-file-spec used on the command line with a default file 
type of LOG. When your batch job completes, this file is printed to the queue 
defined by the logical SYS$PRINT and the file is deleted. 


Note that any process logical names you enter on the DOCUMENT command 
line must be defined in your LOGIN.COM file, otherwise VAX DOCUMENT 
will be unable to translate the logical name during batch processing and will 
issue an error message. 


/CONDITION=condition-name 


Specifies a condition keyword for a conditionalized SDML input file. Using 
this qualifier has the same effect as using the <SET_CONDITION> tag at the 
beginning of your input file. This qualifier accepts a condition-name argument 
that is a text string used to mark the condition being set. 


The /CONDITION qualifier is valid only if tag translation is being done. 
If /NOTAG_TRANSLATOR is specified with the /CONDITION qualifier, 
the /CONDITION qualifier is ignored, and VAX DOCUMENT issues an 
informational message stating that you have specified conflicting qualifiers. 


/CONTENTS 
/NOCONTENTS 


Specifies whether a table of contents file should be produced. The 
/NOCONTENTS qualifier is the default and specifies that no table of 
contents should be produced. When the /CONTENTS qualifier is specified, 
VAX DOCUMENT creates a table of contents file with a file name of 
input-filename_CONTENTS. 


If you place the <CONTENTS_FILE> tag in your SDML file and also specify 
/DEVICE_CONVERTER on the command line, the current table of contents 
file is included at the corresponding point in the final printable output 

file (filename.LNO3, filename.POST, and so on). If you do not place the 
<CONTENTS_FILE> tag in your SDML file, the table of contents is not 
incorporated into your final output file, but is placed in the separate file 
input-filename_CONTENTS and processed separately. 


The file type of this table of contents output file depends upon the destination 
keyword and the processing qualifiers you have selected on the DOCUMENT 
command line. You can use the /KEEP qualifier to retain any intermediate 
table of contents files. 


If you do not specify /CONTENTS on the DOCUMENT command line when 
you process a file that contains a <CONTENTS_FILE> tag, VAX DOCUMENT 
issues warning messages and the most recent version of the table of contents 
file is included. Note that this may result in an out-dated table of contents 
being included in your document. If there is no previous table of contents file 
to be included, the device converter issues an error message. 


bas 


Note: 


DOCUMENT 


The /CONTENTS qualifier is valid only if text formatting is being done. 
If /NOTEXT_FORMATTER is specified with the /CONTENTS qualifier, 
the /CONTENTS qualifier is ignored, and VAX DOCUMENT issues an 
informational message stating that you have specified conflicting qualifiers. 


Note that if you process your document with the /NOTAG_TRANSLATOR 
and /CONTENTS qualifiers, and the table of contents is included using 
the <CONTENTS_FILE> tag, the table of contents is both incorporated into 
your document and placed in the file filename_CONTENTS and processed 
separately. 


The maximum length of a VMS file name is 39 characters. If you want to 
generate a contents file, your input file name must have no more than 30 
characters, because appending _CONTENTS to it adds 9 more characters. 


/DEVICE_CONVERTER|=(device-keyword [,device- 
keyword...])] 
/NODEVICE_CONVERTER 


Specifies whether the device converter should be run. 


The device converter reads and processes an intermediate device-specific 
file and converts it to a file suitable for output on the destination device. 
The output from the device converter has the same file name as the input 
file specified on the command line, and a file type based on the destination 
keyword specified on the command line. 


The /DEVICE_CONVERTER qualifier optionally accepts the following 
keywords for special processing of your file: 





Device Keyword 


Description 


HORIZONTAL _OFFSET=number-of-points Specifies where the text is to be positioned, relative to the left 


edge of the paper. The default horizontal offset for the page is 
one inch (72 points). 


The number-of-points argument specifies the number of points 
the text page should be moved to the right from the left edge 

of the paper. This argument must be zero or a positive integer. 
The left edge of the paper is assumed to be zero. 


VERTICAL _OFFSET=number-of-points Specifies where the text is to be positioned, relative to the top 


edge of the paper. The default vertical offset for the page is 
one inch (72 points). 


The number-of-points argument specifies the number of points 
the text page should be moved ‘oward the page bottom from 
the top edge of the page. This argument must be zero or a 
positive integer. The top edge of the paper is assumed to be 
zero. 


STARTING_PAGE=folio-spec Specifies the beginning page number of the first page in a range 


of pages to be printed. If no ending page is specified, the rest 
of the file is printed. The folio-spec value can be any valid page 
number that VAX DOCUMENT produces on the page’. 


'See the definition of a folio-spec in the description of the /DEVICE_CONVERTER qualifier. 


DOCUMENT 


Device Keyword 


Description 





ENDING__PAGE=folio-spec 


NUMBER_OF_PAGES=maximum-pages 


MULTINATIONAL _CHARACTER_SET 


Specifies the ending page number of the last page in a range of 
pages to be printed. The folio-spec value can be any valid page 
number that VAX DOCUMENT produces on the page’. If both 
the ENDING_PAGE and NUMBER__OF_PAGES keywords are 
used together on the same command line, VAX. DOCUMENT 
issues an error message. 


Specifies the number of pages to print, when no ENDING 
PAGE keyword is specified. If both the ENDING_PAGE and 
NUMBER_OF_PAGES keywords are used together on the same 
command line, VAX DOCUMENT issues an error message. 


_ The maximum-pages value must be an integer specifying the 


total number of pages to print. If this number is specified as a 
number larger than the number of pages in the document (for 
example, 99999), all pages of the document are printed. 


Specifies that the device converter should process the input 
file using the multinational character set. This keyword should 
be used only when you specify a destination keyword that 
does not by default use the multinational character set. 
These destination keywords are LINE_PRINTER, MAIL, and 
TERMINAL. 


'See the definition of a folio-spec in the description of the /DEVICE_CONVERTER qualifier. 


Use the STARTING_PAGE and. ENDING_PAGE keywords to specify the 
page numbers that are to be processed. Each of these keywords accepts a 
folio-spec argument. A folio-spec has the following syntax: _ 


[{folio-prefix}{separator}] {page-number} 


The following list describes the rules for each of the folio-spec syntax 


elements. 


°¢ page-number 


Specifies the page number portion of a folio-spec. In the folio-spec 11-3, 
“3” is the page-number. The page-number can be a Roman number, an 
Arabic number, or an asterisk (*). Roman numbers specify a page in the 
preface of a document, Arabic numbers specify pages outside the preface 
section, and the asterisk (*) specifies the first page of the document 
section specified by the folio-prefix. — 


¢ —folio-prefix 


Specifies the numbers or letters that prefix the folio-spec. A folio-prefix 
can be any of the following: 


— Any single letter. Specifies an appendix in your document, for . 
example the letter “B” in the folio-spec B-6. 


— Any single number. Specifies a chapter number, for example the 
number “13” in the folio-spec 13-1. 


— The keywords GLOSSARY or INDEX. Specify a page in the glossary 
or index, for example “INDEX” in the folio-spec INDEX-6. 


— The keyword PARTn where n is an integer of one or greater. Specifies 
a section begun using a <PART_PAGE> tag, for example “PART2’ in 
the folio-spec PART2-7. : 


DOCUMENT 


_— An asterisk (*). Specifies the first section of your document. 
¢ separator 


Specifies the character that separates the folio-prefix from the page- 
number. The separator can be any single character that is not a space, 
a number, or a letter. In the folio-spec 11-3, “—” is the folio-prefix. A 
separator must be omitted if no folio-prefix is specified, 


The following DOCUMENT command specifies that pages 11-3 through 11-8 
of file MYREPORT.DVI_LNO3 should be processed by the device convertor. 


$ DOCUMENT/NOTAG/NOTEXT myreport REPORT LNO3 - 
_$ /DEVICE=(STARTING=11-3 , ENDING=11-8) 


/DIAGNOSTICS/=file-spec] 
/NODIAGNOSTICS 


Causes the tag translator to write VAX Language-Sensitive Editor (LSE) 
diagnostics records to a file. LSE uses these records during its REVIEW 
phase to locate and describe translation errors. See Appendix B for more 
information on LSE. 


If you omit the file specification, the output file has the same name 
as the input file, with a file type of DIA. The default qualifier is 
/NODIAGNOSTICS. . 


The /DIAGNOSTICS qualifier is valid only if tag translation is being done. 
If /NOTAG_TRANSLATOR is specified with the /DIAGNOSTICS qualifier, 
the /DIAGNOSTICS qualifier is ignored, and VAX DOCUMENT issues an 
informational message stating that you have specified conflicting qualifiers. 


/ELEMENT=file-spec 

Names the file specification of the book element that includes the input file 
specified on the DOCUMENT command line. If you use the /ELEMENT 
qualifier, the /PROFILE qualifier must also be used to specify the profile for 
the book that contains the book element. If you do not specify the file type 
of the element file, the default element file type is SDML. 


The /ELEMENT qualifier is valid only if tag translation is being done. 

If /NOTAG_TRANSLATOR is specified with the /ELEMENT qualifier, 
the /ELEMENT qualifier is ignored, and VAX DOCUMENT issues an 
informational message stating that you have specified conflicting qualifiers. 


/INCLUDE=file-spec 

Specifies a VAX DOCUMENT file that you want to be included before the 
input file you specified on the command line. If you do not specify the file 
type of the file to be included, SDML is the default file type. 


The /INCLUDE qualifier is valid only if tag translation is being done. 

~ If /NOTAG_TRANSLATOR is specified with the /INCLUDE qualifier, © 
the /INCLUDE qualifier is ignored, and VAX DOCUMENT issues an 
informational message stating that you have specified conflicting qualifiers. 


_ /INDEX[=(index-keyword [, index-keyword...])] 


/NOINDEX 

Specifies whether an index file should be produced. The /NOINDEX qualifier 
is the default and specifies that no index should be produced. When the 
/INDEX qualifier is specified, VAX DOCUMENT creates an index file with a 
file name of input-filename_INDEX. 
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Note: 


Index Keyword 


{ GUIDE_HEADINGS 
NOGUIDE_HEADINGS 
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If you place the <INDEX_FILE> tag in your SDML file and also specify 
/DEVICE_-CONVERTER on the command line, the current index file 

is included at the corresponding point in the final printable output file 
(filename.LNO3, filename.POST, and so on). If you do not place the <INDEX_— 
FILE> tag in your SDML file, the index is not incorporated into your final 
output file, but is placed in the separate file input-filename_INDEX. 


The file type of this index output file depends upon the destination keyword 
and the processing qualifiers you have selected on the DOCUMENT 
command line. You can use the /KEEP qualifier to retain any intermediate 
index files. 


If you do not specify /INDEX on the DOCUMENT command line when you 
process a file that contains an <INDEX_FILE> tag, VAX DOCUMENT issues 
a warning message and the most recent version of the index file is included. 
This may result in an out-dated index being included in your document. If no 
previous index file exists, the device converter issues an error message. 


The /INDEX qualifier is valid only if text formatting is being done. If 
/NOTEXT_FORMATITER is specified with the /INDEX qualifier, the /INDEX 
qualifier is ignored, and VAX DOCUMENT issues an informational message 
stating that you have specified conflicting qualifiers. 


Note that if you process your document with the /NOTAG_TRANSLATOR 
and /INDEX qualifiers, and the index is included using the <INDEX_FILE> 
tag, the index is both incorporated into your document and placed in the file 
filename_INDEX and processed separately. . 


The maximum length of a VMS file name is 39 characters. If you want to 
generate an index file, your input file name must have no more than 33 
characters, because appending _INDEX to it adds 6 more characters. 


The following list describes the optional indexing keywords that can be used 
with the /INDEX qualifier. 


Description 
\ Specifies whether alphabetic headings are created for each 
letter group in the index. (The entries beginning with “A” will 


have an A at the start of the group, and so on.) The GUIDE 
HEADINGS keyword is the default. The NOGUIDE_HEADINGS 
keyword suppresses guide headings in the index output file. 


Index Keyword 


SORT=([ { LETTER \ [, 


WORD 


OVERRIDE_MASTER 
NOOVERRIDE_MASTER 


DOCUMENT 


Description 


NONALPHA=BEFORE 


NONALPHA=AFTER 
) 


NONALPHA=IGNORE 


Specifies the sorting algorithm used to order entries in an 
index. 


e SORT=LETTER sorts the entries letter by letter and 
ignores spaces and hyphens. SORT=LETTER is the 
default. 


e SORT=WORD sorts the entries letter by letter and treats 
spaces and hyphens as significant. 


e SORT=NONALPHA positions entries with initial 
nonalphanumeric characters in the index based on the 
keyword supplied with the NONALPHA keyword. 


— The AFTER keyword causes entries with initial 
nonalphanumeric characters to be placed at the end 
of the index. . 


— The BEFORE keyword causes entries with initial 
nonalphanumeric characters to be placed at the 
beginning of the index. 


— The IGNORE keyword causes entries with initial 
nonalphanumeric characters to be sorted by the first 
alphanumeric characters in the entry. The default is 
NONALPHA=IGNORE. . 


Specifies the disposition of all index entries specified with the 
MASTER attribute. When specified during the creation of a 
single-document index, OVERRIDE_MASTER incorporates into 
the single-document index all index entries marked with the 
MASTER keyword. NOOVERRIDE_MASTER is the default, 
that is, index entries marked with the MASTER option will 
normally appear only in the master index. 


/KEEP[=(filetype-keyword [,filetype-keyword... ])] 
/NOKEEP 


Specifies whether intermediate files should be kept or deleted. The default 
qualifier /NOKEEP indicates that the intermediate files should be deleted by 
VAX DOCUMENT after processing. 


The following keywords can be used to specify individual intermediate files 
that are to be kept. 
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File Type 
Keyword File Contents 
DVI Specifies an intermediate output file from the text formatter. You 


may want to keep this file for reprocessing at a later date, or to 
selectively process and print only certain pages. 
The actual file type of this file is based on the destination keyword 
you specified on the DOCUMENT command line. These file types 
and the destination keywords that create them are listed under the 
description of the /TEXT_FORMATTER qualifier. 

INX Specifies an ASCII file that contains index entries in page-number 
order. This file can be used to create master indexes. 

TEX Specifies an input file for the text formatter. Note that a TEX file 
processed under a certain doctype design can produce errors if it 
is reprocessed using a different doctype. 


/LIST 


/NOLIST 


Specifies whether a listing file is produced. The /NOLIST qualifier is the 
default and suppresses the generation of a listing file. The /LIST qualifier 
causes a listing file to be produced with the file name of the input file 
specification and a default file type of LIS. 


The listing file contains the following information: 
e All messages generated by the tag translator 


e All messages generated by the text processor 


e All messages generated by the device converter 


e A brief summary section. This summary includes the following 
information: 


— The original command line 
— The time and day that processing began 
— The total CPU time used 


/LOG 
/NOLOG 


Specifies whether informational messages should be issued during processing. 
The /LOG qualifier is the default and specifies that informational messages 
should be issued. The /NOLOG qualifier suppresses informational messages. 


The following example shows the typical informational messages displayed 
during tag translation (not specifying /NOLOG is the same as specifying the 
default qualifier /LOG): 


$ DOCUMENT myarticle ARTICLE LNO3 

%DOC-I-IDENT, VAX DOCUMENT V1.0 

[Tag Translation]... 
4%TAG-I-TAG_IDENT, V1.0 

“%TAG-I-DEFSLOADD, End of Loading of Tag Definitions 
“%TAG-I-ENDPASS_1, End of first pass over the input 
[Text Formatting]... 


DOCUMENT 


The following example shows the messages displayed during tag translation 
when /NOLOG is specified. Note that the software version and other 
information messages are omitted: 


$ DOCUMENT myarticle ARTICLE LNO3 /NOLOG 
[Tag Translation ].. 
[Text Formatting]... 


If you use the /LIST qualifier with the /LOG qualifier, the /LOG or 
/NOLOG qualifiers control whether informational messages are written 
to the listing file. | 


/MAPI=file-spec] 

/NOMAP 

Specifies whether all the input files processed by VAX DOCUMENT should 
be listed in a file, which starts with the SDML input file and includes the tag 
table and any SDML files specified by the /INCLUDE or /SYMBOLS qualifier 
or the <ELEMENT> or <INCLUDE> tags. Files that are included by other files 


are indented under those files in this listing. The default file type of the file 
to be created is MAP_LIS. The default qualifier is /NOMAP. 


The /MAP qualifier is valid only if tag translation is being done. If 
/NOTAG_TRANSLATOR is specified with the /MAP qualifier, the /MAP 
qualifier is ignored, and VAX DOCUMENT issues an informational message 
stating that you have specified conflicting qualifiers. . 


/MASTER_INDEX 


Causes indexing files to be collated into a master index file. 


When the /MASTER_INDEX qualifier is specified, VAX DOCUMENT expects 
a master index data file as the input-file-spec parameter. This file lists the 
index output (INX) files generated from the individual books that are being 
referenced in the master index. The default file type of this input file is INX— 
LIST. See Chapter 7 for more information on creating a master index. 


/PRINT[=(qualifier-keyword [,qualifier-keyword...])] 


/NOPRINT 


Specifies whether the output file should be printed. The /PRINT qualifier 
builds and issues a DCL PRINT command. You can use any of the DCL 
PRINT command qualifiers with VAX DOCUMENT by passing these 
qualifiers as keywords to the /PRINT qualifier. 


For example, if you want to print two copies of a VAX DOCUMENT file with 
no flag page, you can use the PRINT command as follows: 


$ PRINT somefile.line /NOFLAG/COPIES=2 


You can specify the same options using the following /PRINT qualifier on the 
DOCUMENT command line. 


$ DOC/NOTAG/NOTEXT/NODEV somefile - 
_$/PRINT=(NOFLAG ,COPIES=2) LETTER LINE_PRINTER 


When you use the /PRINT qualifier, you do not need to specify an output 
device; VAX DOCUMENT determines the appropriate output device from the 
destination keyword specified on the DOCUMENT command line. 
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Output 
File Type 


LINE 


LNO3 


POST 


Output 
File Type 


LINE 


LNO3 


POST 
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Print 
Device 


Line Printer 


Default print queues for each of the destination keywords available at your 
site are established when VAX DOCUMENT is installed. These queues 
include all DCL PRINT command qualifiers needed for correct printing on 
that output device. 


If you choose to specify a print queue other than the default, you must 
also specify the correct qualifier-keywords needed for that queue. These 
keywords vary depending on the type of file to be printed (indicated by the 
file extension) and the type of output device. 


The following table shows the keywords to use for each file and output device 
combination. 


DOCUMENT /PRINT Qualifier-Keywords 
/PRINT=(QUEUE=queuename) 


LNO3 Laser Printer 
LNO3 PLUS Laser Printer 


LNO3R SCRIPTPRINTER 


/PRINT=(QUEUE=queuename,PARAM=DATA_TYPE=ANSI) 


PRINTSERVER 40 


LNO3 Laser Printer 


/PRINT=(QUEUE=queuename,NOFEED,PASSALL) 


LNO3 PLUS Laser Printer 


LNO3R SCRIPTPRINTER 


/PRINT=(QUEUE=queuename,PARAM=DAT A_TYPE=ANSI) 


PRINTSERVER 40 


LNO3R SCRIPTPRINTER 


/PRINT=(QUEUVE=queuename,PARAM=DATA_TYPE=POST) 


PRINTSERVER 40 


Print 
Device 


Line Printer 


LNO3 Laser Printer 


If you wish to print your file using the DCL PRINT command, the following 
table shows the qualifiers you must use for each supported device. 


DCL PRINT Command (Qualifiers 


$ PRINT filename.LINE 
_$ /QUEUE=queuename 


LNO3 PLUS Laser Printer 


LNO3R SCRIPTPRINTER 
PRINTSERVER 40 


LNO3 Laser Printer 
LNO3 PLUS Laser Printer 


LNO3R SCRIPTPRINTER 
PRINTSERVER 40 


LNO3R SCRIPTPRINTER 
PRINTSERVER 40 


$ PRINT/PARAM=(DATA_TYPE=ANS)) filename.LINE 
_$ /QUEUE=queuename 


$ PRINT/NOFEED/PASSALL filename.LNO3 
_$ /QUEUE=queuename 


$ PRINT/PARAM=(DATA_TYPE=ANSI) filename.LNO3 
_$ /QUEUE=queuename 


$ PRINT/PARAM=(DATA_TYPE=POST) filename.POST 
_$ /QUEUE=queuename 


When you specify /DEVICE_CONVERTER on the DOCUMENT command 
line, /PRINT is the default printing qualifier when the destination keywords 
are LN03_LASER_PRINTER, POSTSCRIPT, or LINE—PRINTER. The 
/NOPRINT qualifier is the default when the destination keywords are 
TERMINAL or MAIL. 
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Note that if any serious errors are encountered during processing, the file is 
not sent to the print device. 


/PROFILE=file-spec 


Specifies that the input file is a file referenced by the <ELEMENT> tag 

in a bookbuild profile and that a cross-reference data file created by a 

VAX DOCUMENT bookbuild should be used to resolve any cross references 
in the input file. The cross reference data file is specified as an argument to 
the /PROFILE qualifier and has a file type of XREF. 


The /PROFILE qualifier is valid only if tag translation is being done. If 
/NOTAG—_TRANSLATOR is specified with the /PROFILE qualifier, the 
/PROFILE qualifier is ignored, and VAX DOCUMENT issues an informational 
message stating that you have specified conflicting qualifiers. 


/SYMBOLS=file-spec 
/NOSYMBOLS 


Controls whether a file of symbol definitions is to be read automatically 
during tag translation. The default qualifier is /NOSYMBOLS. The SDML 
input file accessed through the /SYMBOLS qualifier should contain only 
symbol definitions created by the <DEFINE_SYMBOL> and the <DEFINE— 
BOOK_NAME> tags. The default file type of this file is SDML. 


The /SYMBOLS qualifier is valid only if tag translation is being done. 

If /NOTAG_TRANSLATOR is specified with the /SYMBOLS qualifier, 
the /SYMBOLS qualifier is ignored, and VAX DOCUMENT issues an 
informational message stating that you have specified conflicting qualifiers. 


/TAG_TRANSLATOR 
/NOTAG_ TRANSLATOR 


Controls whether the tag translator is run. If this qualifier is not specified, the 
default qualifier is /TAG_TRANSLATOR. 


If the input-file-spec parameter specified on the command line does not 
include a file type, the default file type is SDML. By default, the tag translator 
produces an output file with the file name of the input file and a file type of 
TEX. This file can then be used as an input file to the text formatter. — 


/TEXT_FORMATTER 
/NOTEXT_FORMATTER 


Controls whether the text formatting program is run. If /NOTEXT_ 
FORMATTER is specified, VAX DOCUMENT processing stops after the 
tag translator completes. /TEXT_FORMATTER is the default. 


If /NOTAG_TRANSLATOR is specified and the input file specified on the 
command line does not include a file type, the default file type is TEX. The 
output file from the text formatter can have one of several file types based on 
the destination parameter entered on the command line. These default 
output file types and their related destination keywords are given in the 
following list. 
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Destination Intermediate Final 

Keyword Output File Type Output File Type 
LINE_PRINTER DVI_LINE LINE 
LNO3_LASER_PRINTER DVI_LNO3 LNO3 

MAIL DVI_LINE TXT 
POSTSCRIPT DVI_POST POST 

TERMINAL DVI_LINE — TERM 





The output file from the text formatter can then be used as an input file to the 
device converter. 





EXAMPLE When you process your input file using the DOCUMENT command, you are 
actually running your file through several processors. The following example 
shows a typical use of the VAX DOCUMENT command. 


$ DOCUMENT myreport.SDML REPORT LNO3_LASER_PRINTER /CONTENTS 


%DOC-I-IDENT, VAX DOCUMENT V1.0 
[Tag Translation]... 

%TAG-I-TAG_IDENT, V1.0 

4TAG-I-DEFSLOADD, End of Loading of Tag Definitions 
%,TAG-I-ENDPASS_1, End of first pass over the input 
%TAG-I-FILEWRTOK, File MYREPORT.TEX written 

[Text Formatting]... 

“%TEX-I-IDENT, V1.0 

“.TEX-I-PAGESOUT, 17 pages written. 

-TEX-I-OUTFILENAME, ’*DUA1: [DOCFILES]MYREPORT .DVI_LNO3’ 
[Contents Generation] 

{Text Formatting Contents]... 
“%TEX-I-IDENT, V1.0 

4TEX-I-PAGESOUT, 1 page written. 

-TEX-I-QUTFILENAME, ’*DUA1: [DOCFILES]MYREPORT_CONTENTS .DVI_LNO3’ 
[Device Conversion]... 

Y%DVC-I-IDENT, DVC$LNO3 V1.0 

/%DVC-I-PAGESOUT, 18 pages written to file: 

DUA1: [DOCFILES] MYREPORT . LNO3 

[Contents Device Conversion)... 
%DVC-I-IDENT, DVC$LNO3 V1.0 

“%DVC-I-PAGESOUT, 1 page written to file: 

DUA1: [DOCFILES] MYREPORT_CONTENTS . LNO3 

[Printing File]... 

[Printing Contents]... 


Job MYREPORT (queue SYS$LNO3, entry 832) started on SYS$LNO3 
$ 


A-16 


B sUsing LSE with VAX DOCUMENT 


This appendix provides an overview of an optional productivity tool, the 
VAX Language Sensitive Editor. This tool is not included with the VAX 
DOCUMENT software; it must be purchased separately. Using LSE can 
increase your productivity as a VAX DOCUMENT user. For information on 
how to purchase this tool, contact your DIGITAL sales representative. 


B.1 Using LSE with VAX DOCUMENT 


The VAX Language-Sensitive Editor (LSE) is a powerful and flexible text 
editor designed specifically for software development. LSE has important 
features that help you produce syntactically correct SDML markup in VAX 
DOCUMENT. 


To invoke LSE, issue the LSEDIT command followed by a file name with a 
SDML file type at the DCL prompt. For example: 


$ LSEDIT USER.SDML 


The following sections describe some of the key features of LSE. Section B.1.1 
discusses how to enter source code using LSE and Section B.1.2 describes 
LSE’s compiler interface features. Section B.1.3 gives examples of how to 
generate VAX DOCUMENT source code with LSE. 


For more details on advanced features of LSE, see the Guide to VAX Language- 
Sensitive Editor and VAX Source Code Analyzer. 


B.1.1 Entering Source Code Using Tokens and Placeholders 


LSE simplifies the tasks of developing and maintaining documents. LSE 
provides the functions of a traditional text editor, plus additional powerful 
features: language-specific placeholders and tokens, aliases, compile and 
review features. 


Placeholders are markers in the source code that indicate locations where you 
can provide text. Placeholders help you to supply the appropriate syntax in a- 
given context. Generally, you do not need to type placeholders; rather, they 
are inserted for you by LSE. 


Placeholders are either optional or required. Required placeholders, which are 
delimited by braces ({ }), represent places in the source code where you must 
provide text. Optional placeholders, which are delimited by brackets ([ ]), 
represent places in the source code where you can either Proves! additional ° 
constructs or delete the placeholder. 


There are three types of LSE placeholders. 


Using LSE with VAX DOCUMENT 





Type of 

Placeholder Description 

Terminal Provides text that describes valid replacements for the 
placeholder 

Nonterminal Expands into additional language constructs 

Menu Provides a list of options corresponding to the placeholder 


You can move forward or backward from placeholder to placeholder. In 
addition, you can delete or expand placeholders as needed. Section B.1.3 
shows examples of expanding placeholders. 


Tokens typically represent each tag in VAX DOCUMENT. When expanded, 
tokens provide the complete syntax of a tag. You can type tokens directly 
into the buffer. Generally, you use tokens when you want to add a tag and 
there are no placeholders in an existing program. For example, typing COM 
and issuing the EXPAND command causes the tags for a comment to appear 
on your screen. You can also use tokens to by-pass long menus in cases 
where expanding a placeholder, such as [element-or-template], would result 
in a lengthy menu. 


You can use tokens to insert text when editing an existing file by typing the 
name for a function or keyword and issuing the EXPAND command. 


LSE commands allow you to manipulate tokens and placeholders. These 
commands and their default key bindings are as follows: 


Table B—1 LSEDIT Commands 


Key 

Command Binding Function 

EXPAND CTRL/E Expands a placeholder 

UNEXPAND PF1-CTRL/E Reverses the effect of the 
most recent placeholder 
expansion 

GOTO PLACEHOLDER/FORWARD CTRL/N Moves the cursor to the 
next placeholder 

GOTO PLACEHOLDER/REVERSE CTRL/P Moves the cursor to the 
previous placeholder 

ERASE PLACEHOLDER/FORWARD  CTRL/K Erases a placeholder 

UNERASE PLACEHOLDER PF1-CTRL/K Restores the most recently 
erased placeholder 

None Down arrow Moves the indicator down 
through a menu 

None Up arrow Moves the indicator up 
through a menu 

None { ENTER \ Selects a menu option 

RETURN 


You can display a list of all defined tokens and placeholders, or a particular 
token or placeholder, with the LSE commands SHOW TOKEN and SHOW 
PLACEHOLDER. To copy the listed information into a separate file, first issue 
the appropriate SHOW command to put the list into the $SHOW buffer. 
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Then issue the following commands: 


LSE> GOTO BUFFER $SHOW 
LSE> WRITE filename 


To obtain a hard copy of the list, use the PRINT command at DCL level to 
print the file you created. 


B.1.2 Compiling Source Code 


To compile your code and review compilation errors without leaving the 
editing session, you can use the LSE commands COMPILE and REVIEW. 
The COMPILE command issues a DCL command in a subprocess to invoke 
the VAX DOCUMENT tag translator. The compiler then generates a file of 
compile-time diagnostic information that LSE can use to review compilation 
errors. The diagnostic information is generated with the /DIAGNOSTICS 
qualifier that LSE appends to the compilation command. 


For example, to issue the COMPILE command while in the buffer 
USER.SDML, you would use the following command: 


COMPILE $ doctype destination 


The doctype and destination are any valid VAX DOCUMENT keywords. When 
the COMPILE command is issued, the following DCL command executes: 


$ DOCUMENT USER.SDML/DIAGNOSTICS=USER.DIA doctype destination 
LSE supports all of VAX DOCUMENT’s command qualifiers. 


The REVIEW command displays any diagnostic messages that result from 

a compilation. LSE displays the compilation errors in one window and the 
corresponding source code in a second window so that you can review your 
errors while examining the associated source code. This capability eliminates 
tedious steps in the error correction process and helps ensure that all the 
errors are fixed before you recompile your program. 


LSE provides several commands to help you review errors and examine 
your source code. These commands, and their default key bindings where 
applicable, are as follows: 


Command Key Binding Function 

COMPILE None Compiles the contents of the source 
buffer. You can issue this command 
with the /REVIEW qualifier to put LSE 
in REVIEW mode immediately after the 
compilation. 


REVIEW None Puts LSE into REVIEW mode and 
displays any errors resulting from the 
last compilation. 


END REVIEW None Removes the buffer $REVIEW from the 
screen; returns the cursor to a single 
window containing the source buffer. 


GOTO SOURCE CTRL/G Moves the cursor to the source buffer that 
contains the error. 
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Command Key Binding Function 
NEXT STEP CTRL/F Moves the cursor to the next error in the 
buffer $REVIEW. 
PREVIOUS CTRL/B Moves the cursor to the previous error in 
STEP the buffer $REVIEW. 
{ Down arrow \ Moves the cursor within a buffer. 
Up arrow 


The following sections show examples of using some common tokens and 
placeholders to write VAX DOCUMENT code. The examples are expanded 
to show the formats and guidelines LSE provides; however, not all of the 
examples are fully expanded. 


The examples show expansions of the following VAX DOCUMENT features: 
e Tags as tokens: <LIST> and <TABLE> 
e Initial string: [element-or-template] 


e Sample template: Data Item Description (DID) for U.S. Department of 
Defense military specification 


Instructions and explanations precede each example, and an arrow (+) 
indicates the line in the code where an action has occurred. 


See Table B-1 for the commands that manipulate tokens and placeholders. 


Remember that braces ({ }) enclose required placeholders; brackets ({ ]) 
enclose optional placeholders. Note that when you erase an optional 
placeholder, LSE also deletes any associated text before and after that 
placeholder. 


When the editor is used to create a new VAX DOCUMENT file, the initial 
string, {element-or-template}, will appear at the top of the screen. Expansion 
of the initial string will produce the following 


-> [profile] 
(front_matter] 
[chapter] 

[part] 

[appendix] 

[glossary] 

[tag-groups] 

[article-tags] 

[letter-tags] 

{report-tags] 

[overheads-tags] 
{milspec-templates] 
([software-documentation-templates] 


A convention in VAX DOCUMENT is to place a single element, such as a 
chapter or appendix, or a single template, such as a milspec template or a 
software documentation template, into a single file. 


B.1.3.1 


B.1.3.2 
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Lists 
Select the token LIST by typing LIS and expanding the token. 


From the menu of possible list types, select the option Alphabetical-list. The 
following then appears on the screen in the editing buffer: 


<LIST> (ALPHABETIC\ [start-no] \ [case] ) 
{list-element}... 
<ENDLIST> 


Erase the placeholder [start-number] and expand the placeholder [case]. Select 
UPPERCASE. 


<LIST> (ALPHABETIC\UPPERCASE) 
{list-element}... 
<ENDLIST> 


Move to the next placeholder and expand to get an individual list element 
tag. 


<LIST> (ALPHABETIC\UPPERCASE) 
<LE>{t ext} 

[list-element]... 

<ENDLIST> 


Type over the {text} placeholder to insert the text for the first list item. 


Tables | 
Enter all or part of the table token and expand. 


<TABLE>({caption}\ [symbol] ) 
[<TABLE_ATTRIBUTES>] 

<TABLE_SETUP> ({number}[\col-width] ...) 
<TABLE_HEADS> ({heading} [\heading] . . .) 
{rows}... 

<ENDTABLE> 


The <TABLE> tag takes two arguments: the caption to the table and a 
symbol to use for cross references. With the cursor positioned on {caption}, 
enter caption text. With the cursor position on [symbol], enter symbol text. 


-> <TABLE>(Caption for the Table\newsymbol_tab) 
[<TABLE_ATTRIBUTES>] 
<TABLE_SETUP>({number}[\col-width] .. .) 
<TABLE_HEADS> ({heading} [\heading] . . .) 
{rows}... 
<ENDTABLE> 


Next, expand the placeholder <TABLE_ATTRIBUTES> and choose a set of 
attributes from the menu. 


<TABLE>(Caption for the Table\newsymbol_tab) 
-> <TABLE_ATTRIBUTES>(WIDE\MULTIPAGE) 
<TABLE_SETUP> ({number}[\col-width] ...) 


~~~ <TABLE_HEADS> ({heading} [\heading] . . .) 


{rows}... 
<ENDTABLE> 


rd 
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B.1.3.3 


Next, set up the table for the number and width of columns desired. Enter 
a number indicating the number of columns (2 through 9). Then expand the 
[\col-width] placeholder to enter a number indicating the width of the first 
table column. 


<TABLE>(Caption for the Table\newsymbol_tab) 
<TABLE_ATTRIBUTES> (WIDE\MULTIPAGE) 

-> <TABLE_SETUP>(3\{number}[\col-width] ...) 
<TABLE_HEADS> ({heading} [\heading] . . .) 
{rows}... 
<ENDTABLE> 


Notice that the expansion of [\col-width] gives you the backslash needed to 
separate arguments and the {number} placeholder. If you enter a number 
into [\col-width] without expanding it first, you would not get the backslash. 
Enter column widths for each column in the table except the last column. 
Delete the last [\col-width] placeholder. 


<TABLE>(Caption for the Table\newsymbol_tab) 
<TABLE_ATTRIBUTES> (WIDE\MULTIPAGE) 

-> <TABLE_SETUP>(3\15\15 ) 
<TABLE_HEADS> ({heading}[\heading] . . .) 
{rows}... 


The {heading} placeholders work very similarly to the [\col-width] 
placeholder: 


<TABLE>(Caption for the Table\newsymbol_tab) 
<TABLE_ATTRIBUTES> (WIDE\MULTIPAGE) 
<TABLE_SETUP> (3\15\15_ ) 
-> <TABLE_HEADS> (First heading\Second Heading\{heading} [\heading] .. .) 
{rows}. . 
<ENDTABLE> 


Enter a heading for each column and delete the last [\heading] placeholder. 
Expand the {rows} placeholder to get tags for the body of the table. 


<TABLE>(Caption for the Table\newsymbol_tab) 

<TABLE_ATTRIBUTES> (WIDE\MULTIPAGE) 

<TABLE_SETUP>(3\15\15 ) 

<TABLE_HEADS> (First heading\Second Heading\{heading} [\heading] ...) 
-> <TABLE_ROW>({item}[\item] ...) 

(rows]... 


Enter an item for each column and keep expanding the [rows] placeholder 
until the table body is complete. Delete the last [rows] placeholder and the 
table is ready for processing. 


Profile 
To place the tags for a document's his into the editing buffer, type PRO 
and expand the token. 


<PROF ILE> 
{element}... 
<ENDPROF ILE> 
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Expand the placeholder {element} to get the <ELEMENT> tag and the 
optional <INCLUDES_FILE> tag. 


<PROFILE> 
-> <ELEMENT> ({element-name}) 
[<INCLUDES_FILE>] 
{element]... 


<ENDPROF ILE> 


Expand or delete the placeholder <INCLUDES_FILE> and expand the 
placeholder [element] as many times as needed. 


Sample Template 
There are two methods of accessing the Data Item Description (DIDs) 
templates for DOD-STD-2167-related military specifications: 


¢ Select [milspec-templates] from the initial placeholder 


e Enter part of the token “DID-800 ...” and expand to get a list of the 
available data item descriptions 


Select one of the DIDs from the list. 


~> DI-MCCR-80012: Software Top Level Design Document 
DI-MCCR-80025: Software Requirements Specification 
DI-MCCR-80026: Interface Requirements Specification 
DI-MCCR-80027: Interface Design Document 
DI-MCCR-80028: Data Base Design Document 
DI-MCCR-80031: Software Detailed Design Document 


Select one of the DIDs, for example, DI-MCCR-80012. The menu that 
appears is a list of templates that make up the individual files in the Software 
Top Level Design Document. 


For example, select DI-MCCR-80012__cover_page: 


DI-MCCR-80012__profile 
DI-MCCR-80012__symbols 

~> DI-MCCR-80012__cover_page 
DI-MCCR-80012__Scope 
DI-MCCR-80012__Referenced_Documents 
DI-MCCR-80012__Requirements 
DI-MCCR-80012__Qualification_Requirements 
DI-MCCR-80012__Preparation_for_Delivery 
DI-MCCR-80012__Notes 
DI-MCCR-80012__ Appendix 
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Each of the menu items displayed for DI-MCCR-80012 contains a template 
for a section of the Software Top Level Design Document and should be 
placed in a separate file. 


<comment>(begin front matter component) 

<front_matter> 

<title_page> 
<specification_info>(<reference>(control_number) \\<DATE>\) 
<spec_title>(<reference>(DID80012_title)\For the\{text}\ 
Contract No. <reference>(contract_number) \ 

CDRL Sequence No. <reference>(CDRL_number) \<DATE>) 


<subtitle>(Prepared for:\{text}\ \ 
Prepared by: \{text}\{text}) 


<endtitle_page> 
<contents_file> 


<endfront_matter> 
<comment>(end front matter component) 


The tags in the cover page template mark standard title page text. Fill in the 
variable information by typing over the {text} placeholders. 
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To see all of the defined tokens provided by VAX DOCUMENT, enter the 
following Editor command: 


LSE> SHOW TOKEN 


To see all of the defined placeholders provided by the VAX DOCUMENT, 
enter the following Editor command: 


LSE> SHOW PLACEHOLDER 


To print a copy of either of these lists, you must first enter the appropriate 
SHOW command. This enters the list into the $SHOW buffer. Then enter 
the following commands: 


LSE> GOTO BUFFER $SHOW 
LSE> WRITE filename 


At DCL level, you can use the PRINT command to obtain a hard copy of the 
list. 


You may also specify a token name or placeholder name after the SHOW 
TOKEN or SHOW PLACEHOLDER command to obtain information about a 
particular token or placeholder. 


C Messages 


A message has the following format: 
4 facility--severity--identification, text 


Messages in VAX DOCUMENT can come from the following facilities: 


Facility code _— Facility 


DOC The DOCUMENT command line 
TAG The tag translator 

TEX The text processor 

DVC The device converter 

INX The index facility 


The messages from these sources are given in the following sections. 


To locate a message, use the facility code to locate the appropriate section and 
then look for the identification text in that section. Messages are alphabetical 
within sections. 


For example, consider the following message: 


“4TAG-W-ISTHISTAG, at text on line 245 in file 
WRT_: [YOURNAME . BOOK] INTRO. GNC; 
Ignoring <list. Is this a tag without a closing angle bracket? 


The facility code in this error is TAG, so you look in the section for tag 
translator messages. The identification text is ISTHISTAG, so you locate that 
within the section. 


Messages 
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ACTION_EXCL , qualifier is not available for the chosen destination 


Warning: Indicates that the default qualifier has been excluded for the 
desired destination and will therefore be ignored. 


User Action: None. 


AMB_DESIGN , Ambiguous design keyword design-keyword. 


Fatal: Error found while parsing the design data file. There is an ambiguous 
design keyword specified within the file. 


User Action: Change the keyword in error to a unique design keyword. 


AMB_DEST , Ambiguous destination keyword destination keyword. 
Fatal: Syntax error found when parsing the destination data file. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


AMB_DVI_ARG , Ambiguous /DEVICE_CONVERTER argument qualifier-arg. 
Fatal: VAX DOCUMENT cannot parse /DEVICE_-CONVERTER argument. 


User Action: Reexecute DOCUMENT command with a unique qualifier 
argument. 


CANT_ALLOCATE , Cannot allocate enough memory. 
Fatal: VAX DOCUMENT cannot allocate enough memory for its needs. 


User Action: Consult system manager. 


CANT_CONVERT , Cannot convert string-value into an integer. 


Fatal: A numeric value was expected as a qualifier value, but a nonnumeric 
value was found. 


User Action: Reexecute DOCUMENT command when problem is fixed. 


CANT_GET_VALUE , Cannot get value of /qualifier qualifier. 
Fatal: No required value associated with the qualifer. 


User Action: Reexecute DOCUMENT command with a value for the 
qualifier. 


CANT_USE_SHR, Cannot use file-spec. 


Fatal: VAX DOCUMENT could not find or use a shareable image file for text 
processing. 


User Action: Consult system manager. 


DO_CONTENTS, [Contents Generation]... 
Informational: Indicates that a contents file is being created. 


User Action: None. 
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DO_DEVICE, [Device Conversion]... 


Informational: Indicates that the document input is being processed into a 
printable form. 


User Action: None. 


DO_DVC_CONTENTS, [Contents Device Conversion]... 


Informational: Indicates that the document contents is being processed into 
a printable form. 


User Action: None. 


DO_DVC_INDEX, [Index Device Conversion]... 


Informational: Indicates that the document index is being processed into a 
printable form. 


User Action: None. 


DO_INDEX, [Index Generation]... 


Informational: Indicates that an index file is being created from your 
document. 


User Action: None. 


DO_MASTER_INDEX, [Master Index Generation]... 
Informational: Indicates that the master index processor is running. 


User Action: None. 


DO_PRINT, [Printing File]... 


Informational: Indicates that your output file is being sent to designated 
queue. 


User Action: None. 


DO_TAG, [Tag Translation]... 


Informational: Indicates that the tag translator is processing your SDML 
input. 


User Action: None. 
DO_TEXT, [Text Formatting ]... 
Informational: Indicates that the text formatter has started processing. 


User Action: None. 


DO_TEXT_CONTENTS, [Text Formatting Contents ]... 
Informational: Indicates that the text formatter has started processing. 
User Action: None. 

DO_TEXT_INDEX, [Text Formatting Index ].. 
Informational: Indicates that the text formatter has started processing. 


User Action: None. 
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EMPTY_DESIGN , Designs file directory-specDOC$DESIGNS.DAT is empty. 


Warning: Indicates that the DOC$DESIGNS.DAT file contains no design 
information; default design information will be used. 


User Action: Put proper design definitions in the file DOC$DESIGNS.DAT. 
EMPTY_DEST , DOC$DESTINATIONS data file is empty. 


Fatal: Syntax error found when parsing the destination data file. No 
destination specified during installation. 


User Action: Reinstall VAX DOCUMENT, or if you are under a service 
contract with Digital, call your customer service center. Otherwise, submit a 
Software Performance Report. 


ERROR—CONVERTER , Errors found by the Device Converter. 
Error: The device converter has ended in error. Processing cannot continue. 


User Action: Repair errors found by the device converter and reexecute. 


ERROR_FORMATTER , Errors found by the Text Formatter. 
Error: The text formatter has ended in error. Processing cannot continue. 


User Action: Repair errors found by the text formatter and reexecute. 


ERROR_IN_DESIGN , Error in design data file. 
Fatal: Found an unspecified error in the design data file. 


User Action: Correct error in design data file. 


ERROR_IN—DEST , Error in destinations data file, destination keyword entry. 
Error: Syntax error found when parsing the destination data file. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


ERROR_TAG , Errors found by the tag translator. | 
Error: The tag translator has ended in error; processing cannot continue. 


User Action: Repair errors found by the tag translator and reexecute. 


ERR—CRE8_LIST , Cannot create a listing file. 
Fatal; VAX DOCUMENT could not create a listing file. 
User Action: Check privileges and default directory. 


IDENT, VAX DOCUMENT version number 
Informational: DOCUMENT version number identification message. 


User Action: None. 
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INVALID_DESIGN , parameter is not a valid design. 


Fatal: Unrecognized design parameter given on the DOCUMENT command 
line. 


User Action: Reexecute DOCUMENT command with valid design parameter. 


INVALID_DEST , destination keyword is not a valid destination. 
Fatal: Destination parameter is misspelled or nonexistent. 


User Action: Reexecute DOCUMENT command with valid destination 
parameter. 


INVALID_DVI_ARG , qualifier-arg is not a valid /DEVICE_CONVERTER 
argument. 


Fatal: VAX DOCUMENT cannot recognize the argument value of /DEVICE_— 
CONVERTER. 


User Action: Reexecute DOCUMENT command with valid qualifier 
argument. 


INVALID_ENTRY , qualifier-entry is not a valid /qualifier entry. 
Fatal: An invalid qualifier entry was found by VAX DOCUMENT. 


User Action: Refer to Appendix A of this manual for information on valid 
DOCUMENT command line qualifiers. 


INVALID_INPUT , Cannot use file-spec as an input file. 
Fatal: Indicates a problem using the input file-spec as an input file. 
User Action: Reexecute DOCUMENT command with a valid input file 
specification. 
INVALID_VALUE , Cannot use file-spec as a file for /qualifier. 


Fatal: VAX DOCUMENT has a problem opening the input file associated 
with the qualifier. 


User Action: Reexecute DOCUMENT command with valid input file spec. 


MORE—THAN_EIGHT, Only eight parameters allowed when using a command 
procedure. 


Error: Syntax error found when parsing the destination data file. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


NEED_MNEMONIC , Destination entry needs a second parameter. 
Fatal: Syntax error found when parsing the destination data file. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 
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NEED_QUALIFIER , Destination entry needs a /destination qualifier qualifier. 
Fatal: Syntax error found when parsing the destination data file. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


NEED_VALUE , Destination entry parameter needs /VALUE or second 
parameter. 


Fatal: Syntax error found when parsing the destination data file. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


NO_CONTENTS , No contents; /CONTENTS qualifier unnecessary. 
Warning: No contents information was available to generate a contents file. 


User Action: Do not use the /CONTENTS qualifier when processing 
this input file. An SDML file must contain at least one <CHAPTER> , 
<APPENDIX> , or <HEADx> tag to produce a contents file. 


NO_DEFS_FILE , No definitions file file-spec. 
Fatal: No file found with /DEFINITIONS qualifier in the design file. 


User Action: Use a definitions file name. 


NO_FONTS_FILE , No font file file-spec for destination keyword destination. 
Fatal: Font file information not found in destination data file. 


User Action: Correct destination data file to include correct fonts file 
information. 


NO_INDEX , No index; /INDEX qualifier unnecessary. 


Warning: No index file was generated from the input file; /INDEX will not 
produce an index file. 


User Action: Do not use the /INDEX qualifier when processing this input 
file. 

NO_MACROS_FILE , No macro file file-spec for destination keyword destination. 
Fatal: Macro file information not found in destination data file. 


User Action: Correct destination macro file to include correct fonts file 
information. 


OPEN _DESIGN , Error opening directory-specDOC$DESIGNS.DAT data file. 


Warning: Indicates an error occured when trying to open the 
DOC$DESIGNS.DAT data file. 


User Action: Check for existence of DOC$DESIGNS.DAT data file; then 
check privileges and file protection. 
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OPEN_DEST , Error opening DOC$DESTINATIONS data file. 


Fatal: Indicates an RMS error was found when trying to open the destination 
data file. 


User Action: Check for existence of DOC$STANDARD_ 
FORMATS:DOC$DESTINATIONS.DAT, user privileges, or file protection. 


POINTLESS_DEST , DOC$DESTINATIONS data file has no DESTINATION 
entries. 


Fatal: Syntax error found when parsing the destination data file. No 
destination specified during installation. 


User Action: Reinstall VAX DOCUMENT, or if you are under a service 
‘contract with Digital, call your customer service center. Otherwise, submit a 
Software Performance Report. 


PRINT_CONTENTS, [Printing Contents]... 


Informational: Indicates that the contents file is being sent to designated 
print queue. 


User Action: None. 


PRINT_INDEX, [Printing Index]... 


Informational: Indicates that the index file is being sent to designated print 
queue. 


User Action: None. 


TYPE_INPUT , input file 
Informational: Interactive inquiry for the input file. 


User Action: Type the name of the input file at the prompt. 


UNR—DESIGN , Unrecognized design— please check your spelling. 


Fatal: An unrecognized design parameter has been used when calling VAX 
DOCUMENT. 


User Action: Reexecute DOCUMENT command with valid design parameter. 


UNR_DEST , Unrecognized destination— please check your spelling. 
Fatal: The destination parameter to VAX DOCUMENT is invalid. 
User Action: Reexecute DOCUMENT command with a valid destination. 


UNR_DVI_ARG ,_ Unrecognized /DEVICE_CONVERTER argument: qualifier- 
arg. 
Fatal: Unrecognized argument was founded in the device converter qualifier. 


User Action: Reexecute DOCUMENT command with valid /DEVICE— 
CONVERTER argument(s). 
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ABORTFORE, at tag or text on line n of file 
file-spec 
There have been more than number error messages of severity 
level E 


Fatal: The tag translator did not produce an output file because it detected 
too many errors in the SDML source file with a severity level of Error. SDML 
defines the minimum number of error messages of severity E as 0, although 
this default value can be modified in local usage. 


User Action: Examine the output from the preceding messages to determine 
the errors you need to correct. 


ABORTFORW, | at tag or text on line n of file 
file-spec 
There have been more than number error messages of severity 
level W = 


Fatal: The tag translator did not produce an output file because it detected 
too many errors in the SDML source file with a severity level of Warning. 
SDML defines the minimum number of error messages of severity W as 30, 
although this default value can be modified in local usage. 


User Action: Examine the output from the preceding messages to determine 
the errors you need to correct. 


ARGBADOPR, at tag or text on line n of file 
file-spec 
Argument 2 to tag <COUNTER> has an illegal arithmetic operator 


Warning: The tag translator has found an illegal operator. The second 
argument to the <COUNTER> tag consists of pairs of operators and operands, 
and an optional trailing comment. If you receive this message and are under a 
service contract with DIGITAL, call your customer service center. Otherwise, 
submit a Software Performance Report. 


User Action: Verify that the operators and the comment character are correct. 


ARGINCMPL, | at tag or text on line 1 of file 
file-spec 
Argument 2 to tag <COUNTER> is incomplete 


Warning: The tag translator has not found at least one operator and one 
operand. The second argument to the <COUNTER> tag requires at least 
one operator and one operand. If you receive this message and are under a 
service contract with DIGITAL, call your customer service center. Otherwise, 
submit a Software Performance Report. 


User Action: Verify that the second argument begins with an operator and 
an operand. 
ARGMENTIS, The argument is string 


Informational: Follows a message that indicates that an argument is invalid, 
for example, when a numeric argument is required, but a character string 
argument is specified. 


User Action: Use the information to correct your source file. 
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ARGMISSNG, _§ at tag or text on line n of file 
file-spec 
Argument number to tag <tagname> is missing 


Warning: The tag translator found no text for the indicated argument, but 
the argument is required for the indicated tag. 


User Action: Supply a value for the indicated argument. 


ARGNOTCHR, | at tag or text on line n of file 
file-spec 
Argument to tag <CHR> is not in the range 32 to 126 


Warning: The <CHR> built-in tag requires a numeric argument whose value 
is in the range of 32 to 126. If you receive this message and are under a 
service contract with DIGITAL, call your customer service center. Otherwise, 
submit a Software Performance Report. 


User Action: Correct the reference to the <CHR> built-in tag so that it 
specifies a value that is in the correct numeric range. 


ARGNOTKEY, at tag or text on line n of file 
file-spec 
Argument number to tag <tagname> is not a keyword 


Warning: The argument in the indicated position is not a valid keyword 
argument for the indicated tag. This message is generally followed by a 
message that shows the keyword that was specified. 


User Action: Using the information in this message and the accompanying 
message, determine the keyword in error. Check the VAX DOCUMENT User 
Manual, Volume 1 to determine the valid arguments for the tag in question 
and correct your source file. 


ARGNOTLET, at tag or text on line n of file 
file-spec 
Argument to tag 9<SET_APPENDIX_LETTER> is not a letter 


Warning: The <SET_APPENDIX_LETTER> tag requires a letter (A to Z). 


User Action: Correct the source file to supply a letter as the first character of — 
the argument. 


ARGNOTMSG, _§at tag or text on line n of file 
file-spec 
‘Argument number to tag <tagname> is not a valid message 
code 


Warning: The indicated argument to the <TAG_DIAGNOSTIC> built-in tag is 
not a recognized message code. If you receive this message and are under a 
service contract with DIGITAL, call your customer service center. Otherwise, 
submit a Software Performance Report. 


User Action: Verify the spelling of the message code and correct your source 
file. 
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ARGNOTNAM, | at tag or text on line n of file 
file-spec 
Argument number to tag <tagname> is not a valid name 


Warning: The indicated argument does not obey the rules for formation of 
a name. A name must have only letters, digits and the underscore character. 
A name must not begin with two underscores. Spaces, tabs, and carriage 
returns are not allowed. 


User Action: Correct the argument so that the name is valid. 


a ARGNOTNUM, at tag or text on line n of file 
file-spec 
Argument number to tag <tagname> is not a number 


Warning: A non-numeric argument was specified to a tag that requires a 
numeric argument. 


User Action: Verify that the argument is in the correct position in the tag’s 
argument list. Supply a numeric argument to the tag. 


ARGNOTPOS, at tag or text on line n of file 
file-spec 
Argument to tag 9<SET.CHAPTER_NUMBER> is not a positive 
integer 


Warning: The <SET_CHAPTER_NUMBER> tag requires a positive integer for 
the chapter number argument. 


User Action: Correct the source file to supply a positive integer. 


ARGNOTTYP, at tag or text on line n of file 
file-spec 
Argument string to tag <tagname> is not valid for doctype string 


| Warning: The indicated argument is not valid for this tag in the indicated 
doctype. 


User Action: Verify that you specified the correct doctype keyword on the 
DOCUMENT command line. 


ARGOUTRAN, | at tag or text on line n of file 
_ file-spec 
Argument number is not in the range 0 to 9 


Warning: The indicated argument cannot be less than 0 or greater than 9. 


User Action: Correct the argument so that the number is in range. 


ARGOVRFLW, at tag or text on line n of file 
file-spec 
More than number characters in an argument 


Fatal: The argument is too large. This often indicates that an argument 
list was not terminated correctly. The tag translator may be including large 
portions of the input text as part of the argument. 


User Action: Check the tag indicated by the location information and supply 
the correct termination to the argument list. 
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AUXOVRFLW, at tag or text on line n of file 
file-spec 
More than number auxiliary files open 


Fatal: The number of auxiliary files that can be open simultaneously is 
limited. If you receive this message and are under a service contract with 
DIGITAL, call your customer service center. Otherwise, submit a Software 
Performance Report. 


User Action: Be sure to close an auxiliary file when you have finished 
reading or writing it. 


BADLSTARG, at tag or text on line n of file 
file-spec 
Argument string is not valid for <LIST> type string 


Warning: Verify the argument you specified to the <LIST> tag. Each type of 
list accepts different keyword arguments, for example, UPPERCASE is a valid 
keyword for alphabetic lists, but not for numbered lists. 


User Action: Verify that you have specified the correct type of list. If you 
specify a keyword argument, be sure that it is spelled correctly. 


BNOTESOUT, at tag or text on line n of file 
file-spec 
Accumulated string not referenced 
Notes will not be output 


Warning: A document contained <BACK_NOTE> or <BIB_NOTE> tags, but 
no corresponding <BACK _NOTES> or <BIB_NOTES> was specified to output 
the accumulated notes. 


User Action: Place the <BACK_NOTES> or <BIB_NOTES> tag in the source 
file at the position at which you want them output. 


BOXTOOBIG, at tag or text on line n of file 
file-spec 
Length number of boxed item exceeds number characters 


Warning: An argument to the <BOX> tag exceeds the maximum number of 
characters allowed. The text will be output as null. 


User Action: Correct the <BOX> tag to specify an argument with fewer 
characters. 


CALL_NEST, at tag or text on line n of file 
file-spec . 
Callouts inaccurately nested in a monospaced example 


Error: A monospaced example using callouts with the keyword PREFIX 
incorrectly nests the example tags with the <CALLOUT> tags. For example, 
the following is incorrect: 


<CALLOUTS> (\PREFIX) 
<CODE_EXAMPLE> 


<ENDCALLOUTS> 
<ENDCODE_EXAMPLE> 
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User Action: Correct the SDML source file so that the begin and end tags for 
the example and the callouts are correctly nested, for example: 


<CALLOUTS> (\PREF IX) 
<CODE_EXAMPLE> 


<ENDCODE_EXAMPLE> 
<ENDCALLOUTS> 


COMNOTEND, | at tag or text on line n of file 
file-spec 
A <COMMENT> ina tag definition has not been terminated 


Error: A tag’s definition contains a comment that is not properly terminated. 


User Action: Examine the tag definition to be certain that the comment 
text is terminated. If the comment text contains characters such as 
ampersand, backslash, vertical bar, or parentheses, use the <COMMENT> ... 
<ENDCOMMENT> format. 


CPU_USAGE, Pass 1: number Pass 2: number Total: number seconds 


Informational: The tag translator reports its cpu usage during pass 1 and 
pass 2 and the total for both passes. 


User Action: None. 


CPYNAMHID, at tag or text on line n of file 
file-spec 
<COPY_TAG> is referencing a tag ( <tagname> ) that is hidden 


Warning: The name referenced by the <COPY_TAG> is hidden, and therefore 
cannot be copied as a new tag definition. If you receive this message and are 
under a service contract with DIGITAL, call your customer service center. 
Otherwise, submit a Software Performance Report. 


User Action: Be sure that the name is spelled correctly and that the sequence 
of tag executions allows the copy to take place when the tag is not hidden. 


CPYNAMUND, at tag or text on line n of file 
file-spec 
<COPY_TAG> is referencing a name (string) that is undefined 
Warning: The name referenced by the <COPY_TAG> is not defined, and 
therefore cannot be copied as a new tag definition. If you receive this message 


and are under a service contract with DIGITAL, call your customer service 
center. Otherwise, submit a Software Performance Report. 


User Action: Be sure that the name is spelled correctly and that the tag is 
already defined. 


DEFSLOADD, End of Loading of Tag Definitions 


Informational: This message is issued after the tag definitions have been 
loaded and before the reading of any input files. If any error messages appear 
before this message, the errors were detected during the loading of the tag 
definitions. 


User Action: None. 
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DIVBYZERO, at tag or text on line n of file 
file-spec 
Argument 2 to tag <COUNTER> is attempting to divide by : zero 


Warning: Division by zero is undefined. (Processing continues. The result 
is as if a divisor of 1 had been used.) If you receive this message and are 
under a service contract with DIGITAL, call your customer service center. 
Otherwise, submit a Software Performance Report. 


User Action: Verify that the correct divisor is specified. You may want to use 
the <COMPARE_NUMERIC> built_in tag to test the divisor before using it. 


DUPHIDNAM, at tag or text on line n of file 
file-spec 
A <HIDE_TAGS> tag is reusing the hide-name, string 


Warning: The hide-name is already in use. Once tags have been hidden 
under a specific hide-name that hide-name cannot again be used until the 
tags have been revealed with the <REVEAL_TAGS> tag. If you receive this 
message and are under a service contract with DIGITAL, call your customer 
service center. Otherwise, submit a Software Performance Report. 


User Action: Examine the sequence in which <HIDE_TAGS> and <REVEAL— 
TAGS> tags are invoked using the indicated hide-name. Correct the sequence 
so that the hide and reveal actions alternate in sequence. 


DUPSYMBOL, at tag or text on line n of file 
file-spec 
The symbol string is being defined twice 
The earlier definition is replaced by the new definition 


Warning: The same symbol is being defined for two different purposes. The 
tag translator requires that each symbol be unique. If your symbols exceed 31 
characters in length, the automatic truncation to 31 characters may be causing 
two different symbols to look alike. 


User Action: Verify that both symbols are defined uniquely within the first 
31 characters. 


ENDNOTBEG, _§at tag or text on line n of file 
file-spec 
<tagname> specified without corresponding <tagname> 


Warning: A terminating tag was specified without the tag that it terminates. 
The tag is ignored. 


User Action: Verify that you correctly entered the beginning tag. Or, remove 
the extraneous ending tag from your source file. 


ENDPASS_1, End of first pass over the input 


Informational: The tag translator reports the end of the first pass over all 
input files. Error messages that appear ahead of this message were issued 
during the first pass. Error messages that follow this message are issued 
during the second pass over the input files. 


User Action: None. 
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EOFARGLST, End of file encountered while searching for closing 


parenthesis. See argument list of tag <tagname> on line number 
of file 
filename 


Fatal: An argument list is not terminated before the end of the current input 
file. Either a right parenthesis is missing, or an <INCLUDE> tag occurred in a 
tag’s argument list. 


User Action: Verify that the indicated tag’s argument list is terminated, and 
that no tag’s argument list is unterminated at the end of an included file. 


EOFCOLECT, End of file encountered while searching for tag <tagname> 


See <COLLECT> tag on line number of file 
filename 


Fatal: A <COLLECT> built-in tag has encountered an end of file before 

encountering the indicated stop-tag. If you receive this message and are 
under a service contract with DIGITAL, call your customer service center. 
Otherwise, submit a Software Performance Report. 


User Action: Verify the spelling of the stop-tag argument, and the presence 
of the stop-tag in the input file. 


EOFENDCAS, End of file encountered while searching for tag <ENDCASE> 


See <CASE> or <CASE_NUMERIC> tag on line number of file 
filename 


Fatal: A <CASE> (or <CASE_NUMERIC> ) built-in tag is not terminated 
before the end of file. If you receive this message and are under a service 
contract with DIGITAL, call your customer service center. Otherwise, submit 
a Software Performance Report. 


User Action: Verify that every <CASE> and <CASE_NUMERIC> built-in tag 
is terminated by an <ENDCASE> tag, even if the <CASE> built-in tags are 
nested. 


EOFENDCOM, End of file encountered while searching for tag <ENDCOMMENT> 


See <COMMENT> tag on line number of file 
filename 


Fatal: Comment text, introduced by the <COMMENT> built-in tag, was not 
enclosed as an argument, and therefore requires an <ENDCOMMENT> tag as 
a terminator. 


User Action: Verify that the comment text is either enclosed as an 
argument to the <COMMENT> built-in tag, or that it is terminated with 
an <ENDCOMMENT> tag. 


EOFENDLIT, End of file encountered while searching for tag <ENDLITERAL> 


See <LITERAL> tag on line number of file 
filename 


Fatal: Literal text, introduced by the <LITERAL> built-in tag, was not 


enclosed as an argument, and therefore requires an <ENDLITERAL> tag 
as a terminator. 


User Action: Verify that the literal text is either enclosed as an argument to 
the <LITERAL> built-in tag, or that it is terminated with an <ENDLITERAL> 
tag. 
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EOFIGNORE, at tag or text on line n of file 
file-spec 
End of file encountered while searching for tag or label 


Fatal: An <IGNORE> built-in tag has encountered the end of the input file 
without finding one of the tags or labels supplied in the argument list. If you 
receive this message and are under a service contract with DIGITAL, call your 
customer service center. Otherwise, submit a Software Performance Report. 


User Action: Verify the spelling of the tags and labels in the argument list. 
You may want to add the label _ EOF to the argument list. 


ERRCLSINP, at tag or text on line n of file 
file-spec 
Input files not closed at end of pass 


Fatal: Files that were included as part of the input have not been properly 
closed. 


User Action: Submit a Software Performance Report. 


ERRDEFLNM, | at tag or text on line n of file 
file-spec 
Attempt to define logical name was unsuccessful 
Logical: string 
Equivalence:string 


Warning: An <INCLUDES_FILE> tag in the <PROFILE> template has failed in 
its attempt to define the logical name with the given equivalence string. 


User Action: Examine the arguments to the <INCLUDES_FILE> tag to ensure 
that they are a correctly formed name and a file specification. Correct the 
<INCLUDES_FILE> arguments. 


ERRDURGET, at tag or text on line n of file 
file-spec 
Error reading line number of file: 
filename. 
Perhaps the line is too long 


Warning: The indicated line probably exceeds the tag translator’s buffer size. 
Processing continues with a truncated line (which may introduce other errors 
if the information that was lost includes part of an argument list to a tag). 


User Action: Edit the input file and shorten the line, or break it into two 
lines if possible. 


ERRDURPUT, at tag or text on line n of file 
file-spec 
Error detected writing output file: 
filename 


Fatal: An error was detected while attempting to write to the indicated output 
file. 


User Action: Check that your process has sufficient privilege and access 
rights and that the output device has sufficient free space to hold the file. 
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ERROPEAUx, at tag or text on line n of file 


file-spec 
Cannot open auxiliary file: 
filename 


"Warning: An attempt to open an auxiliary file failed. The next Informational 


message may supply the reason for the failure. Processing continues, but 
attempts to read or write the auxiliary file will fail and will generate error 
messages. If you receive this message and are under a service contract with 
DIGITAL, call your customer service center. Otherwise, submit a Software 
Performance Report. 


User Action: If the file is being opened for input, verify that the correct file i: 
being accessed and can be read. If the file is being opened for output, verify 

that the file specification is correct, and that you have sufficient resources and 
access rights to create the file. 


ERROPEDMP, at tag or text on line n of file 


file-spec 
Cannot open dump file: 
filename 


Warning: The <RETRIEVE> built-in tag has failed to open a file for output. 
The next Informational message may indicate the reason for the failure. If 
you receive this message and are under a service contract with DIGITAL, 
call your customer service center. Otherwise, submit a Software Performance 
Report. 


User Action: Verify that the file specification is correct, and that you have 
sufficient resources and access rights to create the file. 


ERROPEINC, at tag or text on line n of file 


file-spec 
Cannot open included file: 
filename 


Warning: The indicated file cannot be opened for input. The next 
Informational message may indicate the reason for the failure. Processing _ 
continues without the included file. 


User Action: Verify that the correct file is being accessed and can be read. If 
you are using a logical name to access the file, verify that the logical name 

is defined. If you are relying on an <INCLUDES_FILE> tag to define the 
logical name, verify that the spelling of the logical name is the same in the 
<INCLUDES_FILE> tag, and that the <INCLUDES_FILE> tag has been specified 
for the book element that contains the <INCLUDE> tag. 


ERROPEINP, at tag or text on line n of file 


file-spec 
Cannot open input file: 
filename 


Fatal: The input file specified on the command line cannot be opened. The 
next Informational message may indicate the reason for the failure. 


User Action: Verify that the correct file is being accessed and can be read. 


Messages 
Tag Translator Messages 


ERROPELOG, at tag or text on line n of file 
file-spec 
Cannot open log file: 
filename 


Warning: The <SET> built-in tag has failed to open a file for trace output. 
The next Informational message may indicate the reason for the failure. If 
you receive this message and are under a service contract with DIGITAL, 
call your customer service center. Otherwise, submit a Software Performance 
Report. 


User Action: Verify that the file specification is correct, and that you have 
sufficient resources and access rights to create the file. 


ERROPEOUT, at tag or text on line n of file 
file-spec 
Cannot open output file: 
filename 


Fatal: The tag translator cannot open the output file. The next informational 
message may indicate the reason for the failure. 


User Action: Verify that the file specification is correct, and that you have 
sufficient resources and access rights to create the file. 


ERROPESEC, at tag or text on line n of file 
file-spec 
Cannot open secondary output file: 
filename 


Warning: An attempt to open a secondary output file failed. Processing 
continues, but output will go to the primary output file. If you receive this 
message and are under a service contract with DIGITAL, call your customer 
service center. Otherwise, submit a Software Performance Report. 


User Action: Verify that the file specification is correct, and that you have 
sufficient resources and access rights to create the file. 


ERROPESIN, at tag or text on line n of file 
file-spec 
Cannot open cross reference input file: 
filename 


Fatal: The tag translator failed to open the file that contains the symbols used 
for cross-references. The next information message indicates the reason for 
the failure. 


User Action: The file that contains the symbols used in cross-referencing can 
be used by only one user at a time. The tag translator locks the file to ensure 
that users have only serial access to it. If the reason for the failure to open 
the file was due to the fact that another user was currently using the file, you 
must wait and reissue the command when the file is no longer in use. 
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ERROPESOT, at tag or text on line n of file 
file-spec 
Cannot open cross reference output file: 
filename 


Fatal: The tag translator failed to open a file for writing the symbols used for 
cross references. The next informational message may indicate the reason for 
the failure. 


User Action: Verify that you have sufficient resources and access rights to 
create the file. 


ERRVMZONE, at tag or text on line n of file 
file-spec 
Internal error. Failure to create VM zone. 


Fatal: The tag translator failed to create space in virtual memory for storage 
of data. 


User Action: Submit a Software Performance Report. 


EXAMINLIN, Examine line number of file filename 


Informational: This message follows other messages of greater severity, and 
directs you to a possible error in the input. 


User Action: Use the information to examine and correct your input. 


EXFOOTNOT, at tag or text on line n of file 
file-spec 
Footnotes in a monospaced example exceeds maximum of 4 


Warning: You have specified more than four <FOOTNOTE> tags in a 
<CODE_EXAMPLE> or other monospaced example. The maximum allowed is 
four. The footnote will not be processed. 


User Action: Correct the source file by removing the extraneous footnotes. 


EXPAPPLET, Explicit appendix letter string set on line number of file 
filename 


Informational: This message warns that the letter assigned to the next 
<APPENDIX> tag has been supplied explicitly by a <SET_APPENDIX_LETTER> 
tag. The appendixes may be lettered out of sequence. 


User Action: No action is required. 


EXPAPPNUM, Explicit appendix number number set on line number of file 
filename 


Informational: This message warns that the number assigned to the next 
<APPENDIX> tag has been supplied explicitly by a <SET_APPENDIX— 
NUMBER> tag. The appendixes may be numbered out of sequence. 


User Action: No action is required. 
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EXPCHAPNO, Explicit chapter number number set on line number of file 
filename 


Informational: This message warns that the number assigned to the next 
<CHAPTER> tag has been supplied explicitly by a <SET.CHAPTER_NUMBER> 
tag. The chapters may be numbered out of sequence. 


User Action: No action is required. 


FILEWRTNG, File filename written (0 length) 


Informational: An Error or Fatal message has been issued during the tag 
translation of a book element. The output file for that book element is 
reduced to 0 length. 


User Action: Correct the problems indicated in the Error and Fatal messages 
and reprocess. 


FILEWRTOK, File filename written 


Informational: An element of a book has been processed through the tag 
translation phase. 


User Action: None. 


FCMDPARMS, § at tag or text on line n of file 
file-spec 
<tagname> specified without <tagname> in Format 
Using <tagname> alone 


Warning: The tags <FCMD> and <FPARMS> must be used together to 
produce predictable results. 


User Action: Modify your source file so that it contains both the <FCMD> 
and <FPARMS> tags. Arguments to either of these tags may be null, that is, 
it is valid to specify <FCMD>. 


FIG_DEPTH, at tag or text on line n of file 
file-spec 
Tag <tagname> value number exceeds the maximum NUMBER or 
is 0 
Warning: The indicated tag specifies a depth for a figure or space to be left 
for a figure that will overrun the page boundaries. Or, the argument was 
specified as 0. In either case, the document's default full page depth will be 
used. 


User Action: Correct the tag so that you specify no more than the maximum 
allowed. 


FIG_WIDTH, at tag or text on line n of file 
file-spec 
Tag <tagname> value number exceeds the maximum NUMBER or 
is 0 
Warning: The indicated tag specifies a width for a figure or space to be left 
for a figure that will overrun the page boundaries. Or, the argument was 
specified as 0. In either case, the document’s default full page width will be 
used. 


User Action: Correct the tag so that you specify no more than the maximum 
allowed. 
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FIGINDENT, at tag or text on line n of file 
file-spec 
The value number specified for a block indent exceeds the 
current allowed maximum of number 


Warning: A <FIGURE_FILE> tag specified the INDENT argument and a value 
that exceeds the current maximum allowed. The maximum value will be 
used. 


User Action: Correct the numeric argument specified with INDENT so that it 
does not exceed the indicated maximum. 


FIGLINMAX, at tag or text on line n of file 
file-spec 
Monospaced example lines in <tagname> exceed maximum 
number 


Error: A monospaced example specified in the context of a <FIGURE> or 
<EXAMPLE> tags is too long to fit on the current page and either no <VALID_ 
BREAK> tags were specified to provide valid break points, or there are too 
many lines between <VALID_BREAK> tags. 


User Action: Put <VALID_BREAK> tags at suitable places in the monospaced 
example to allow the pages to break automatically. 


FILENUMNG, | at tag or text on line n of file 
file-spec 
File number is out of range 


Warning: A number supplied to the <FILE_NAME> tag is not within the 
range of 1 to the number of files that have been opened. If you receive this 
message and are under a service contract with DIGITAL, call your customer 
service center. Otherwise, submit a Software Performance Report. 


User Action: Do not attempt to pass a number to the <FILE_NAME> tag 
unless that number was previously returned by an invocation of the <FILE_ 
NUMBER> tag. This guarantees that only legal file numbers will be used as 
arguments to the <FILE_NAME> tag. 


FILISOPEN, at tag or text on line n of file 
file-spec 
Auxiliary file: 
filename 
is already open 


Warning: An <OPEN> built-in tag is specifying a file that is already open. 
The request is ignored, and processing continues. If you receive this message 


and are under a service contract with DIGITAL, call your customer service 
center. Otherwise, submit a Software Performance Report. 


User Action: Check the file specification to be sure that the correct file is 
being specified. Remove the second request to open the same file. 
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FILNOTOPN, at tag or text on line n of file 
file-spec 
Auxiliary file: 
filename 
is not open 


Warning: A.<READ> or <WRITE> built-in tag is addressing a file that 

has not been opened. If you receive this message and are under a service 
contract with DIGITAL, call your customer service center. Otherwise, submit 
a Software Performance Report. 


User Action: Verify that the file is being correctly referenced and that the file 
has been opened with the <OPEN> built-in tag. 


FMTDEVICE, Tag <tagname> produces device-specific output 


Informational: A tag that produces specific formatting controls has been 

_ processed. The output may not be suitable if the file is processed for another 
document type, destination, or both. For example, <FINAL_CLEANUP> (LINE_ 
BREAK) tells the text processor to create a new line of output, but the line 
break may not be suitable on all output devices. 


User Action: Use explicit formatting commands sparingly. 


GTMAXARGS, at tag or text on line n of file 
file-spec 
More than number arguments supplied to tag <tagname> 


Error: The indicated tag does not expect more than the indicated number 


of arguments. Perhaps you included a backslash character in one of the 
arguments, which the tag translator interpreted as an argument separator. 


User Action: Verify that the argument list is correctly coded. If necessary, 
use the <BACKSLASH> tag to code a backslash character that is actually part 
of an argument. 


HIDNOTHID, | at tag or text on line n of file 
file-spec 
Internal error. A hidden tag was invoked, 
but was not found in the data structure of hidden tag names 


Fatal: The algorithm for hiding and revealing tags has failed. If you receive 
this message and are under a service contract with DIGITAL, call your 
customer service center. Otherwise, submit a Software Performance Report. 


User Action: Submit a Software Performance Report. 
ICON_TEXT, at tag or text on line n of file 


file-spec 
No text supplied for <ICON>. 


Warning: An <ICON> tag was specified, but no <ICON_TEXT> tag specified 
text to accompany the graphics. No text will be output. 


User Action: Verify that you specified <ICON_TEXT> correctly. 
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IGNAMEILL, at tag or text on line n of file 


file-spec 
Argument string to <IGNORE> is illegal 


Warning: The argument is not a legal name or label. The argument is 
dropped from the argument list, and processing continues. If you receive this 
message and are under a service contract with DIGITAL, call your customer 
service center. Otherwise, submit a Software Performance Report. 


User Action: Examine the argument list to the <IGNORE> tag. 


IGNAMEMIS, at tag or text on line n of file 
file-spec . 
An argument to <IGNORE> tag is a null string 


Warning: One of the arguments to an <IGNORE> tag is empty. If you 
receive this message and are under a service contract with DIGITAL, call your 
customer service center. Otherwise, submit a Software Performance Report. 


User Action: Examine the argument list to the <IGNORE> tag. The tag 
names should not have brackets around them. 


IGNORESET, Ignoring <SET_CHAPTER-NUMBER> or <SET_APPENDIX_LETTER> ~ 
on line number of file 
filename 


Informational: The <SET_CHAPTER-NUMBER> and <SET_APPENDIX_LETTER> 
tags are ignored when doing a bookbuild or element build, because the 
numbering of book elements is done automatically. 


User Action: Remove the tag. 


IGNOTDONE, at tag or text on line 7 of file 
file-spec 
The <IGNORE> tag has no arguments, so it is ignored 


Warning: Missing or illegal arguments have resulted in an <IGNORE> tag 
that has no legal arguments. The <IGNORE> tag is not executed. If you 
receive this message and are under a service contract with DIGITAL, call your 
customer service center. Otherwise, submit a Software Performance Report. 


User Action: Examine the argument list to the <IGNORE> tag. 


INCNOTARG, | at tag or text on line n of file 
file-spec 
An <INCLUDE> tag cannot be invoked in an argument 


Error: An <INCLUDE> tag can be invoked only in text. 
User Action: Move the <INCLUDE> tag outside the argument list. 


INCOVRFLW, at tag or text on line n of file 


file-spec 
More than number nested levels of included files 


Fatal: The number of included files that can be open at the same time is 
limited. The limit has been exceeded. 


User Action: Consider whether the included files can be included 
sequentially rather than simultaneously. If file A includes file B, and file 

B includes file C, consider whether file A can include both B and C, one after 
the other. 
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INDENTVAL, at tag or text on line n of file 
file-spec 
The <tagname> specifies an indent value of number 
This exceeds the maximum number allowed for this tag 


Warning: The INDENT argument to the specified tag specified an indent 
value that exceeds the maximum allowed. The maximum value will be used. 


User Action: Correct the tag to specify an indent value less than or equal to 
the maximum allowed. 


INT_LOGIC, at tag or text on line n of file 
file-spec 
Internal error processing tag <NAME> 


Error: An SDML tag definition has an error in it. 


User Action: Submit a Software Performance Report. 


ISTHISTAG, at tag or text on line n of file 

file-spec 

Ignoring <string. Is this a tag without a closing angle bracket? 
Warning: An apparent tagname has been found, but without the closing | 
angle bracket that is needed to make it a complete tag invocation. This 
sometimes occurs when an underscore is typed as a hyphen. For example, 
<TABLE_SETUP> is typed as <TABLE-SETUP>. The tag translator stops on the 
hyphen because that is an illegal character in a tagname, and it assumes that 
you may have meant to type <TABLE> -. 


User Action: If this is a typo, simply add the closing angle bracket or change 
the hyphen to an underscore. If this is not a typo (you really want the left 
angle bracket and the tagname to appear in the output), use the <LITERAL> 
tag to enclose the left angle bracket. This action will suppress the warning 
message. 


KEYPADROW, _§at tag or text on line n of file 
file-spec 
Too many keypad rows. Extra rows ignored 
Warning: A set of tags within a <KEYPAD_SECTION> specifies more than 
four <KEYPAD_ROW> tags. The keyboard keypad has only four rows and 
one end row. 


User Action: Determine which <KEYPAD_ROW> tag is extra and remove it 
from your source file. 
LASTAGWAS, Last occurrence of <tagname> was on line number 


Informational: This message is issued when a tag is not ended before a 
particular context or the end-of-file. It tells you the line number of the last 
occurrence of the tag. 


User Action: Use the indicated line number to determine where to correct 
your source file. 
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LISTYPWAS, List type was string 


Informational: This message accompanies an error that indicates that a 
<LIST> tag was not terminated. It indicates the type of list, for example, 
NUMBERED, UNNUMBERED, and so on. 


User Action: Use this information to correct your SDML source file. 


LITOVRFLW, More than number characters in literal. See line number of file 
filespec . 


Fatal: The size of the text encompassed by a <LITERAL> tag is limited. 
This error may indicate that a <LITERAL> tag was incorrectly terminated, 
however. 


User Action: Verify that the <LITERAL> tag has been correctly coded. If the 
text to be encompassed by the <LITERAL> tag exceeds the limit, you must 
break it up and use more than one <LITERAL> tag. 


LTMINARGS, at tag or text on line 7 of file 
file-spec 
Fewer than number arguments supplied to tag <tagname> 


Error: The indicated tag requires a minimum number of arguments. Perhaps 
one of the arguments has an unmatched right parenthesis in it, and the tag 
translator has treated that character as the terminator of the argument list. 


User Action: Review and correct the argument list. Be sure that the open 
parenthesis for the argument list is not preceded with a space, for example 
<TAG> (ARG) should be <TAG> (ARG). 


MARKUNBAL, _ at tag or text on line n of file 
file-spec 
<MARK> tags are unbalanced 


Error: A <MARK> tag and its corresponding <ENDMARK> tag cross a tag’s 
boundary or are incorrectly nested with respect to another pair of tags. For 
example, if a <MARK> tag is specified before <FORMAT> and <ENDMARK> 
is specified before <ENDFORMAT> , the tags are considered unbalanced. 


User Action: Look at the source file location of the indicated tag, and move 
it. In particular look for instances where a <MARK> tag is specified in a tag 
argument, but the <ENDMARK> tag is specified outside that tag’s argument 
or in an argument to another tag. 


MINEXCMAX, at tag or text on line n of file 
file-spec 
Minimum argument count (number) exceeds maximum argument 
count (number) 
(Minimum argument count is being reset to zero) 


Warning: A <DEFINE> or <REDEFINE> tag is specifying a minimum and 
maximum number of arguments and the minimum exceeds the maximum. 

If you receive this message and are under a service contract with DIGITAL, 
call your customer service center. Otherwise, submit a Software Performance 
Report. 


User Action: Correct the minimum and maximum argument values. 
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MSGIDISNG, at tag or text on line n of file 
file-spec 
The message identification string is invalid 
The <HIDE_TAGS> tag is ignored 


Warning: The second argument to a <HIDE_TAGS> tag is supplying an 
unknown message identification. If you receive this message and are under a 
service contract with DIGITAL, call your customer service center. Otherwise, 
submit a Software Performance Report. 


User Action: Check the spelling of the message identification argument to be 
sure that it agrees with one of the error messages in the message file. 


NAMETRUNCG, at tag or text on line n of file 
file-spec 
Name string exceeds 31 characters 
Name string is truncated version 


Warning: Names may not exceed 31 characters in length. The name that was 
supplied is a legal name, but it is too long. It is truncated to 31 characters. 


If more than one name is truncated, the shortened names may not be unique 
and other errors may occur depending on the type of name. 


User Action: Shorten this name (and any other names that are too long) to 
31 characters or less, so that there is no potential for other errors. 


NAME2LONG, | at tag or text on line n of file 
file-spec 
Condition name string exceeds 28 characters 


Error: Condition names may not exceed 28 characters in length. 


User Action: Shorten this name (and any other condition names that are too 
long) to 28 characters or less. 


NESTEDCOM, A <COMMENT> tag on line number of file 
filename 
is nested within <COMMENT> ... <ENDCOMMENT> that starts on 
line number of file . 
filename 


Warning: <COMMENT> tags cannot be nested. 


Sometimes an error is made in typing a <COMMENT> tag in the format 
<COMMENT> (text). The typo makes it appear that the tag does not have an 
argument list, and it is assumed that an <ENDCOMMENT> tag is present to 
end the comment text. During the search for the <ENDCOMMENT> tag, if 
another <COMMENT> tag is encountered it will appear to be nested within 
the first <COMMENT> tag’s text. 


User Action: Correct any typographical errors in the initial <COMMENT> tag 
or remove the nested <COMMENT> tag. 
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NODEFITEM, at tag or text on line n of file 


file-spec 
Definition list specified no items before <tagname> 


Warning: A <DEFINITION_LIST> tag, or a corresponding tag in the 
SOFTWARE doctype, was specified but no <DEFLIST.ITEM> / <DEFLIST_ 
DEF> tags were specified for the list. No output will be produced. 


User Action: Remove the definition list start/end tags; or provide item text 
for the definition list. 


NOENDPROF, | at tag or text on line n of file 
file-spec 
The <PROFILE> tag was not terminated by an <ENDPROFILE> 
tag 


Warning: In order for the bookbuild process to be completed, the <PROFILE> 
tag must be terminated by an <ENDPROFILE> tag. The <ENDPROFILE> tag is 
supplied by default in this case. 


User Action: If the <PROFILE> tag is not terminated by an <ENDPROFILE> 
tag, add one after the final <ELEMENT> or <INCLUDES_FILE> tag. 


NOFIGELMS, at tag or text on line n of file 
file-spec 
<tagname> has no elements. 


Warning: A <FIGURE> or <EXAMPLE> tag was specified and terminated 
but there were no elements (for example, <FIGURE—SPACE> ), to place in the 
figure. 


User Action: Verify that you correctly spelled and entered tags for the figure 
or example. 


NOHIDERVL, at tag or text on line 1 of file 
file-spec 
Ignoring request to hide the <REVEAL_TAGS> tag 


Warning: The <REVEAL_TAGS> built-in tag cannot be hidden by the action 
of a <HIDE_TAGS> built-in tag. If you receive this message and are under a 
service contract with DIGITAL, call your customer service center. Otherwise, 
submit a Software Performance Report. 


User Action: Remove the word REVEAL_TAGS from the argument list of 
the <HIDE_TAGS> tag. 


NONESTING, at tag or text on line n of file 
file-spec 
Invalid attempt to nest tag <tagname> . Ignored 
Warning: A tag is referenced when its context is already active. For example, 


this message is issued when <CODE_EXAMPLE> is specified when a previous 
<CODE_EXAMPLE> is not terminated. 


User Action: The indicated tag is ignored; however, you should verify your 
source file to determine whether the tag is a duplicate or whether, in fact, you 
did not terminate an earlier occurrence of the same tag. 
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NONEWFILE, at tag or text on line n of file 
file-spec 
<tagname> specified without string. No new file will be 
generated 


Warning: A <CONTENTS_FILE> or <INDEX_FILE> was encountered in the 

input file, but the corresponding /CONTENTS or /INDEX qualifier was not 
present on the command line. No new contents or index will be produced. 

An earlier version of a contents or index file, if it exists, may be included in 
the output. 


User Action: If you want to include the current table of contents or index 
file, you should reissue the DOCUMENT command using the appropriate 
qualifier. 


NOPROFILE, at tag or text on line n of file 
file-spec 
Tag can appear only following a <PROFILE> tag 


Fatal: The tag is part of a profile and can be used only in that context and 
only within the same file as the <PROFILE> tag. 


User Action: Check that the tag appears after a <PROFILE> tag, and in the 
same file as the <PROFILE> tag. 


NOREADOUT, at tag or text on line n of file 
file-spec 
Cannot read from file: 
filename 
The file is opened as output 


Warning: A <READ> built-in tag cannot be addressed to an auxiliary file 
that is opened as output. (The <OPEN> tag defaults to output mode unless 
INPUT is specified.) If you receive this message and are under a service 
contract with DIGITAL, call your customer service center. Otherwise, submit 
a Software Performance Report. 


User Action: Correct the <OPEN> built-in tag to open the file as input. 


NOTDOCTYP, at tag or text on line n of file 
file-spec 
Tag <tagname> is not allowed in the string doctype 


Error: The indicated tag is not meaningful in the context of the doctype 
specified on the command line and cannot be processed. For example, the 
LETTER doctype does not allow <CHAPTER> or heading-level tags. 


User Action: Verify that you specify the correct doctype keyword on the 
DOCUMENT command line. If the doctype is correct, remove the tags from 
the SDML source file. 
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NOTHIDNAM, | at tag or text on line n of file 


file-spec 
A <REVEAL_TAGS> tag is referencing an unknown hide-name, 
string 


Warning: The hide-name specified by a <REVEAL_TAGS> tag is not in use. 
If you receive this message and are under a service contract with DIGITAL, 
call your customer service center. Otherwise, submit a Software Performance 
Report. . . 


User Action: Examine the sequence in which <HIDE_TAGS> and <REVEAL_ 
TAGS> tags are invoked using the indicated hide-name. Correct the sequence 
so that the hide and reveal actions alternate in sequence. 


NOTINELEM, | at tag or text on line n of file 


file-spec | 
Tag can appear only within the context established by 
an element heading tag such as <CHAPTER>, <PART> , etc 


Error: When a bookbuild is done, all text and the tags that accompany the 
text must appear within some element of the book. The text and tags must 
follow the element heading tag in order to be considered to be in the context 
of the element. 


User Action: Correct the source text so that the tag that is in error follows a 
tag that heads an element of the book. 


NOTINPROF, at tag or text on line n of file 


file-spec 
The <tagname> tag must appear in the same file as the 
<PROFILE> tag 


Error: All the tags that make up a profile must appear in the same file. 


User Action: Move the tag into the same file as the <PROFILE> tag. 


NOZONEYET, at tag or text on line n of file 


file-spec 
Tag <tagname> specified outside its valid zone or context 
It must be preceded by tag <tagname> 


Error: A tag was specified outside the context that enables it, for example, a 
<COPYRIGHT_PAGE> tag was specified when the tag <FRONT_MATTER> has 
not been specified to enable the front matter zone. 


User Action: Be sure that you have specified the correct tag. Add the 
appropriate zone-enabling tag. 


NOWRITEIN, _ at tag or text on line n of file 


file-spec 

Cannot write to file: 
filename 

The file is opened as input 


Warning: The <WRITE> built-in tag cannot write to an auxiliary file that has 
been explicitly opened as input. If you receive this message and are under a 
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service contract with DIGITAL, call your customer service center. Otherwise, 
submit a Software Performance Report. 


User Action: Correct the <OPEN> built-in tag or use the proper tag 
(<READ> or <WRITE> ) to agree with the mode in which the file has been 
opened. 


NOUNDEFBI, at tag or text on line n of file 
file-spec 
Ignoring <UNDEFINE> or <REDEFINE> of the built-in definition of 
<tagname > 


Warning: A tag translator built-in tag cannot be deleted by the action of a 
<REDEFINE> or <UNDEFINE>. The built-in tag can be “stacked” by issuing 
a <DEFINE> tag for it, however. If you receive this message and are under a 
service contract with DIGITAL, call your customer service center. Otherwise, 

submit a Software Performance Report. 


User Action: Change a <REDEFINE> to a <DEFINE>. Change an 
<UNDEFINE> to a <DEFINE> that has an empty definition. 


OTL_—TITLE, at tag or text on line n of file 
file-spec 
<tagname> not valid within outlines 
Enter the title as an argument to the <OUTLINE> tag 


Warning: A <TITLE> tag was specified within the context of the 
<OUTLINE> tags. 


User Action: Correct your source file so that the title of the outline is 
supplied in arguments to the <OUTLINE> tag. 


OTL_LEVEL, at tag or text on line n of file 
file-spec 
Outline level specified, number, is not in range 
The argument must specify 1 through 6 


Warning: An invalid number was specified in a <LEVEL> tag in an outline. 
Only levels of 1 through 6 are valid. 


User Action: Correct your source file so that no outline level has a number 
greater than 6. 


OUTLIN2BG, at tag or text on line n of file 
file-spec 
Output line exceeded number bytes, and had to be broken 


Warning: Text in an output line exceeded the tag translator’s buffer. No text 
was lost because the line was written as two lines, but the division into two 
lines may have broken a word into two words, or interfered with the correct 
formatting of the text. This usually happens when the tag translator inserts a 
great many formatting commands into an output line. It also happens when 
a tag reference on a long input line is replaced by a very long string of text. 


User Action: Check the formatted output that corresponds to the input line 
specified in the location information to see if breaking the line affected the 
formatting. 
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POSTERROR, at tag or text on line n of file 
file-spec 
Error encountered during post-translation 


Fatal: An error has been detected during the final step in tag translation. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


PQLISNONE, at tag or text on line n of file 
file-spec 
<tagname> _ specifies NONE’ when no heading is specified 


Warning: The keyword argument “NONE” was specified to a 
<PARAMDEFLIST> or <QUALDEFLIST> tag in a context in which no default 
heading is in effect. The use of NONE in this context is meaningless. 


User Action: Determine if you intended to be using default headings for 
the <PARAMDEFLIST> or <QUALDEFLIST> tag. If not, remove the tag from 
your source file. Otherwise, verify whether you should have invoked one 
of the reference templates to set an environment for parameter/qualifier list 
descriptions. 


QUALVALUE, at tag or text on line n of file 
file-spec 
Value string to /CONDITION qualifier is not a valid name 


Fatal: The condition name supplied with the /CONDITION qualifier must 
contain only alphabetic and numeric characters and the underscore character. 


User Action: Correct the spelling of the condition name. 


REV_PAGES, Update pages number through number will be output. 


Informational: This message indicates the pages that will be output for an 
update. 


User Action: None. 


REVISINFO, Document is using revision indicators 


Informational: This message indicates that the <REVISION> tag is being 
processed. Text that is delimited by <MARK> and <ENDMARK> tags will be 
accompanied by revision indicators on output. 


User Action: If you intend for revision bars to print in your text, you do 
not need to take any action. However, if you intended for text indicated 
by <MARK> tags to not appear in the output, you should remove the 
<REVISION> tag from the file. 


REVISTEXT, Revised pages will contain the text ‘string’. 


Informational: This message verifies the text specified in the second 
argument to the revision tag and reminds you that only pages specified 
in an update range will be processed and printed. 


User Action: None. 
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REVIS_UPD, Revision will contain update pages only 


Informational: This message reminds you that you specified 

<REVISION> (UPDATE) and that your output file will only contain the text 
for pages specified between <UPDATE_RANGE> and <ENDUPDATE_RANGE> 
tags. 


User Action: None. 


RMVCONDTN, Removing condition condition-name 
on line number of file filespec 


Informational: A <SET_CONDITION> (REMOVE) tag is being executed. 


User Action: None. 


SAVTAGACT, at tag or text on line n of file 
file-spec 
Tag <tagname> has a before or after action that is 
ignored when saving a tag table 


Warning: You are attempting to invoke a tag that has a before action or an 
after action. The before action or after action cannot be executed while you 
are saving the tag in a tag table. The before action or after action will be 
executed when the saved tag table is loaded. If you receive this message and 
are under a service contract with DIGITAL, call your customer service center. 
Otherwise, submit a Software Performance Report. 


User Action: No action. However, you may want to verify that this tag 
should be invoked when the saved tag table is actually loaded. 


SAVTAGILL, at tag or text on line n of file 
file-spec 
This built-in tag cannot be invoked during the saving of a tag table 


Error: Only certain built-in tags can be stored in a saved tag table for 
invocation when the saved tag table is loaded. This tag is not one that can 
be saved. If you receive this message and are under a service contract with 
DIGITAL, call your customer service center. Otherwise, submit a Software 
Performance Report. 


User Action: Examine your need to invoke this tag when the tag table is 
loaded. If you still need to invoke the tag, store it as a quoted string in a 
string variable. Then reference the string variable. Here is an example: 


Suppose that you want to invoke the <FILE_NAME> tag during the loading 
of the saved tag table. You must store the <FILE_NAME> tag in a string and 
then output the string. 


<STRING> (my_—file_name\| <FILE_NAME> &) 
<STRING> (my_—file_name) 


This works because the <STRING> tag is one of the tags that can be saved in 
the saved tag table. 
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-SAVTAGLEV, at tag or text on line n of file 


file-spec 
Tag <tagname> cannot be invoked within an argument list 
during saving of a tag table | 


Error: During the saving of a tag table, the arguments to all tags must be 
constant or must be made constant by quoting them. If you receive this 
message and are under a service contract with DIGITAL, call your customer 
service center. Otherwise, submit a Software Performance Report. 


User Action: Place a vertical bar before the first character of the argument 
and an ampersand after the last character of the argument. } 


SDML_INFO, message 


Informational: An SDML tag is describing action taken during tag loading. 


User Action: None. The message is purely informational. 


SECFILOPN, at tag or text on line n of file 


file-spec 

Cannot open a secondary output file named 
filename 

A secondary output file is already open. It is named 
filename 


Error: Only one secondary output file can be open at a time. If you receive 
this message and are under a service contract with DIGITAL, call your 
customer service center. Otherwise, submit a Software Performance Report. 


User Action: Use the <CLOSE_SECONDARY_OUTPUT> tag to close any 
secondary output file before using the <OPEN_SECONDARY_OUTPUT> tag 
to open a new file. 


SETCONDTN, Setting condition condition-name 


on line number of file filespec 


Informational: A <SET_CONDITION> tag is being executed or a condition is 
being set in response to a /CONDITION qualifier on the command line. 


User Action: None. 


SKIPITEMS, at tag or text on line n of file 


file-spec 
number .<tagname> outside of <tagname> skipped. 


Warning: This message is usually preceded by a message indicating that an 
<LE> or <TABLE_ROW> tag was encountered; it indicates the number of 
additional tags that were specified. The tags will not be processed, and will 
be written, unformatted, to the output file. 


User Action: Determine if the tags are considered invalid because there is no 
preceding <TABLE> or <LIST> tag, or if the <TABLE> or <LIST> tag was 
specified incorrectly. Correct your source file. 
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STKOVRFLW, at tag or text on line n of file 
file-spec 
More than number nested levels of tags. (These are 
tags that are invoked inside other tags’ argument lists) 


Fatal: The tag translator limits the number of tags that can be invoked 
simultaneously. Tag B is invoked simultaneously with tag A, if it is invoked 
in the argument list to tag A. Thus, <A> (<B> (<C> )) requires that three 
tags are being invoked simultaneously. This may occur unexpectedly when 
the argument list to one of the tags is not properly terminated. 


User Action: Verify that the argument list of the tag that is specified in the 
location information has been properly terminated. 


STRFREEBA, at tag or text on line n of file 


file-spec 
Internal error. Attempt to free string with bad address 


Fatal: The tag translator’s memory allocation algorithm has failed. 


User Action: Submit a Software Performance Report. 


STRFREE2T, at tag or text on line n of file 
file-spec 
Internal error. Attempt to free the same string twice 


Fatal: The tag translator’s memory allocation algorithm has failed. 


User Action: Submit a Software Performance Report. 


STRTOOBIG, at tag or text on line n of file 
file-spec 
Internal error. Attempting to allocate number-byte string 


Fatal: The tag translator’s memory allocation algorithm has failed. — 


User Action: Submit a Software Performance Report. 


SYMFREEBA, at tag or text on line n of file 
file-spec 
Internal error. Attempt to free symbol table entry with bad address 


Fatal: The tag translator’s memory allocation algorithm has failed. 


User Action: Submit a Software Performance Report. 


SYMISSING, at tag or text on line n of file 
file-spec 
Missing symbol argument 
Each book element must have a symbol argument 


Fatal: Each element of a book must have a unique symbol so that the element 
can be processed independently. The symbol table cannot be saved from this 
run. 


User Action: Supply a symbol as an argument to the tag. 
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SYMISUSED, at tag or text on line n of file 
. file-spec 
The symbol string is already in use as a symbol of type string 


Error: Each element of a book must have a unique symbol. You have 
supplied a symbol on this element of the book that conflicts with an earlier 
use of this symbol. The symbol table cannot be saved from this run. 


User Action: Correct the use of symbols on elements of the book so that each 
element has a unique symbol. If you are doing a bookbuild you must repeat 
the bookbuild in order to produce a good symbol table. If you are doing an 
element build, just correct the symbol in this tag so that this element of the 
book has a unique symbol and then repeat the element build. 


SYMNOTDEF, at tag or text on line n of file 
file-spec 
Symbol string is undefined 


Warning: A symbol has been referenced but is not in the symbol table. 


User Action: Verify that the symbol is spelled correctly and that the same 
symbol has been entered in the symbol table by the invocation of a tag that 
defines the symbol. 


TAG_FAILS, The tag translator has detected a fatal error 


Error: The tag translator is terminating execution with failure status. The 
accompanying error message supplies details of the error. 


User Action: See the description of the accompanying error message. 


TAG_IDENT, _ string 


Informational: The tag translator identifies itself, including name and version 
number. 


User Action: None. 


TAGFREEBA, at tag or text on line n of file 
file-spec 
Internal error. Attempt to free tag table entry with bad address 


Fatal: The tag translator’s memory allocation algorithm has failed. 


User Action: Submit a Software Performance Report. 


TAG_INARG, | at tag or text on line 1 of file 
file-spec 
<tagname> is invalid in an argument to <tagname> . 


Fatal: The indicated tag was specified in an argument to a tag that does not 
allow it. For example, a header level tag was specified in an argument to 
<TABLE_ROW> . 


User Action: Verify that you correctly terminated the argument list for the 
tag in which this tag was specified. 
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TAGINFILE, The tag was in the file filename 


Informational: This message may accompany a message indicating that a tag 
that must be ended was not terminated. This message is output when the 
starting tag is not in the current input file. 


User Action: Use the file-spec given to determine which file contains the tag 
that was not properly terminated and terminate it. 


TAGINVALD, _ at tag or text on line n of file 
file-spec 
Tag <tagname> is invalid in this context 
The context was established by <tagname> on line number of 
filename 


Error: A tag was specified in a context where it is not valid, for example, a 
header-level tag was specified within the context of a monospaced example. 
The message tells you what tag established the context. 


User Action: Determine the current context at the point at which the message 
was issued to determine if you have forgotten a required terminator and 
correct your source file. 


TAGINZONE, at tag or text on line n of file 
file-spec 
Tag <tagname> is invalid in the bounds of string. 


Error: A tag was specified in a context where it is not valid, for example, a 
header-level tag was specified within the context of a monospaced example. 


User Action: Determine the current context at the point at which the message 
was issued to determine if you have forgotten a required terminator and 
correct your source file. 


TAGNOTDEF, at tag or text on line n of file 
file-spec 
Tag <tagname> is undefined 


Warning: A tag has been invoked, but no definition exists for the tag. This 
message appears for the first invocation of an undefined tag. Subsequent 
invocations of the same undefined tag are counted, but the message is not 
repeated. A count of the total number of all invocations of undefined tags is 
reported at the end of the tag translator’s processing. 


User Action: Correct the spelling of the tag, or supply a definition for the 
tag. 
TAGNOTEND, at tag or text on line n of file 
file-spec 
Tag <tagname> from line number not terminated 
Error: A tag that has a required terminator was not terminated. 


User Action: Locate the tag that was not terminated and include its - 
terminating tag at the appropriate position in your source file. 
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TAGNOTHID, | at tag or text on line n of file 
file-spec . 
Cannot reveal tag <tagname> . It is not hidden 


Warning: A <REVEAL_TAGS> tag is requesting that a hidden tag be revealed, 
but the tag is not currently hidden. If you receive this message and are 
under a service contract with DIGITAL, call your customer service center. 
Otherwise, submit a Software Performance Report. 


User Action: After a tag is hidden through the action of a <HIDE_TAGS> 
tag, it can only be revealed through the action of a <REVEAL_TAGS> tag. If 
the tag is given a new definition (using the <DEFINE> tag) while it is hidden, 
it will not appear to be hidden when the <REVEAL_TAGS> tag is executed, 
and this error message will occur. Check the sequence of your use of the 
<HIDE_TAGS> , <DEFINE>, and <REVEAL_TAGS> tags. 


TAGNOTPRE, at tag or text on line 1 of file 
file-spec 
Tag <tagname> invalid unless preceded by string 


Warning: A tag is being invoked that is invalid because it is being used out 
of context. 


User Action: Check the sequence of tags to ensure that the proper context is 
established before the tag is used. Correct the SDML source file. 


TBLATTRIB, at tag or text on line n of file 
file-spec 
Argument string to tag <tagname> is not a valid table attribute 


Warning: A keyword was specified in a <TABLE_ATTRIBUTES> tag that is not 
a valid keyword attribute for tables. 


User Action: Verify that the specified value is a valid table attribute and 
check its spelling. Correct the SDML source file. 


TBLATTIGN, at tag or text on line n of file 
file-spec 
<TABLE_ATTRIBUTES> specified following <TABLE_SETUP> 
ignored | 


Warning: The <TABLE_ATTRIBUTES> tag must be specified preceding the 
<TABLE_SETUP> tag. The specified attributes will be ignored. 


User Action: Move the <TABLE_ATTRIBUTES> tag in front of the <TABLE_ 
SETUP> tag. 


TBLCOLCNT, at tag or text on line n of file 
file-spec 
Tag <TABLE_SETUP> argument 1 ’string’ is missing or is not a 
number in the range 2 through 9 


Error: The <TABLE_SETUP> tag must specify a numeric value in the range 
of 2 through 9 to specify the number of columns in the table. The indicated 
argument is invalid. 


User Action: Correct the <TABLE_SETUP> tag. 
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TBLCOLNUM, | at tag or text on line n of file 
file-spec 
Table column size argument ‘string’ is missing or is not numeric 


Error: An argument specified as a width for table rows in setting up the table 
is not a numeric argument. 


User Action: Correct the <TABLE_SETUP> tag that specifies a non-numeric 
value for a table column width. 


TBLDUPSET, at tag or text on line n of file 
file-spec 
Tag <TABLE_SETUP> specified twice. Duplicate setup ignored 


Warning: A table contains two <TABLE_SETUP> tags. The second tag is 
being ignored. 


User Action: Determine which <TABLE_SETUP> tag is correct and remove 
the extra one. 


TBLFNOTEM, ' at tag or text on line n of file 
file-spec 
Table footnote number number exceeds maximum number 


Warning: A numeric argument specified for a footnote declaration in a table 
exceeds the maximum. The maximum number of table footnotes is normally 
12; however, if you use any non-numeric keywords in table footnotes, the 
maximum number allowed is reduced to 6. 


User Action: Verify the number of footnotes in the table, and the numeric 
arguments you use to declare and reference them. 


TBLKEYDUP, at tag or text on line n of file 
file-spec 
Table already specifies <TABLE_KEY>. Duplicate ignored 


Warning: Only one key can be specified in a table. The second key specified 
is being ignored. 


User Action: Determine which table key is the one that you want and 
remove the duplicate one. 


TBLKEYNES, at tag or text on line n of file 


file-spec 
<tagname> is not valid in a nested table 
Nested table on line string in file string 


Warning: A <TABLE_KEY> or <TABLE_KEYREF> tag was specified in a 
nested table, that is a table that is specified in another table’s <TABLE_ROW> . 
Table keys and table key references are invalid in nested tables. 


User Action: Place the table key and/or the reference to it in the outer table. 
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TBLKEYNUM, | at tag or text on line n of file 


file-spec 
The <TABLE_KEY> tag will replace table footnote 12. 


Warning: When a key is specified in a table, you cannot specify a table 

footnote numbered 12. The text of the table key will replace the footnote 

number 12, and references to footnote 12 will result in the table key being 
printed. 


User Action: Check the arguments you specified to the <FOOTNOTE> tags in 
the table and do not specify a number greater than 11. 


TBLKNOREF, | at tag or text on line n of file 
file-spec 
Tag <TABLE_KEYREF> tag encountered in a table that has no key. 


Warning: A <TABLE_KEYREF> tag is not valid because there is no key in the 
table to reference. 


User Action: Verify that the <TABLE_KEY> tag is correctly specified in the 
main table (it must not be specified in a nested table). If the table has no key, 
remove the <TABLE_KEY> tag. 


TBLNBREAK, at tag or text on line n of file 
file-spec 
A nested table with more than three columns cannot be broken 


Error: The <NESTED_TABLE_BREAK> was specified in a nested table that has 
more than three columns. 


User Action: Verify that the <TABLE_SETUP> tag for the table you are trying 
to break was correctly specified. If the nested table has four columns, you 
may need to restructure your information. 


TBLNONEST, at tag or text on line n of file 
file-spec 
Invalid attempt to nest a formal table. Ignored 


Warning: You coded a nested table incorrectly. There are two possible 
problems: 


e You specified a <TABLE> tag with a caption argument in an argument 
to a <TABLE_ROW> tag. You cannot place a formal table inside another 
formal table. 


e¢ You specified a <TABLE> tag inside another table, but outside of a 
<TABLE_ROW> tag. All text (including nested tables) that occur within a 
table must be coded within <TABLE_ROW> tags. 


User Action: For the first case, remove the caption argument from the nested 


table tag. For the second case, place your nested table inside a <TABLE_ 
ROW> tag. 
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TBLNOROWS, at tag or text on line n of file 


file-spec 
A table was specified without any table rows 


Error: <TABLE> and <ENDTABLE> tags were encountered in the file, but 
there were no <TABLE_ROW> tags between them. 


User Action: Verify that you specified <TABLE_ROW> tags correctly. Or, 
remove the <TABLE> and <ENDTABLE> tags if you did not want to place a 
table there. 


TBLNOTDEC, at tag or text on line n of file 
file-spec 
Table footnote number is referenced but not declared. 


Warning: A <FOOTREF> tag is specified in a table, but there is no 
corresponding <FOOTNOTE> tag at the beginning of the table. The footnote 
reference will not be printed. 


User Action: Verify that you specified the <FOOTNOTE> tag correctly at the 
beginning of the table. Verify that the number specified in the declaration 
matches the number in the <FOOTREF> tag. 


TBLNOTSET, at tag or text on line n of file 


file-spec 
Table from line number has no <TABLE_SETUP> attributes 


Error: A <TABLE_ROW> tag was encountered in a table without a <TABLE_ 
SETUP> tag. 


User Action: Correct your source file to specify the number of columns and 
widths for the table. 


TBLNOTMTP, at tag or text on line n of file 
file-spec 
<tagname> invalid in table that is not multi-page 


Error: A tag, for example <TABLE_UNIT> was specified in a table that does 
not have the multipage attribute. 


User Action: Determine whether the table is a multipage table. If so, be sure 
that it is not specified with the KEEP attribute. 


TBLTOOWID, at tag or text on line n of file 
file-spec 
Sum of table column widths number will exceed text margins 
The maximum width for the current doctype is number 


Error: The sum of the values specified for the column widths in the <TABLE_ 
SETUP> tag exceeds the default for the current document design. The 
message displays the current summed value of all column widths specified, 
and the maximum value you can specify. 


User Action: Verify that the numbers you specified in <TABLE_SETUP> 

are accurate. Adjust them to smaller numbers so that the table will fit. If 

you did not specify <TABLE_ATTRIBUTES> (WIDE) and the document design 

you are using provides an extra margin for wide tables, specify <TABLE_ 

ATTRIBUTES> (WIDE) in front of the <TABLE_SETUP> tag. To request that the 
- table appear in a smaller typesize, use <TABLE_ATTRIBUTES> (MAXIMUM). 
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TMPNONEST, | at tag or text on line n of file 
file-spec 
Invalid attempt to nest reference templates 
Last template was string 


Error: A tag invoking a reference template was encountered when a reference 
template was already in effect; for example, a <ROUTINE_SECTION> is 
specified before a previous <COMMAND_SECTION> was terminated. 


User Action: Correct your source file to correctly terminate the reference 
section that was not terminated. 


TMPTAGDEF, You cannot redefine <tagname> using <tagname> . 


Informational: A tag that defines a template tag specified a tag name that is 
already a defined tag. This message indicates one of the following: 


¢ Your input file has more than one reference template section, and 
you use the same template tag names in both. (For example, a <SET_ 
TEMPLATE_ROUTINE> tag may specify the same tag name in more than 
one occurrence of <ROUTINE_SECTION> . 


e¢ You have specified a name that is the name of an SDML global tag. 


User Action: If the message occurred because you used the same template 
tag names in more than one reference template section, you need take no 
action. If you have used a name that is the name of an SDML tag, you 
should select another name; future use of the SDML tag name in the same 
source file may produce unpredictable results. 


TMPTAGEND, at tag or text on line 1 of file 


file-spec 
<tagname> not terminated before <tagname> 


Warning: A tag occurring within the context of a reference template was 
not terminated before the end of the file or before the beginning of the next 
reference section. For example, an <OVERVIEW> tag from a <COMMAND> 
description was not terminated before the next <COMMAND> description was 
encountered. 


User Action: Correct the source file so that you correctly terminate the 
template tag. 


TMPTAGNAM, _§ at tag or text on line n of file 
file-spec 
string is an invalid template tag name 


Error: A template tag, for example <SET_TEMPLATE_COMMAND> , specifies 
that the tag name is already defined in SDML, or it is an invalid name, that is, 
it contains more than 31 characters or it contains nonalphanumeric characters. 


User Action: Choose another name for the tag, and modify your source file. 
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UNDEFSYMS, There were number undefined symbol references 


Informational: This message reports the total number of references that were 
made to undefined symbols. Only the first reference to a specific undefined 
symbol is reported. 


User Action: Either define the undefined symbol, or correct the spelling of 
the symbols being referenced. The undefined symbols were reported in other 
messages. 


UNDEFTAGS, There were number undefined tag invocations 


Informational: This message reports the total number of invocations of 
undefined tags. Only the first invocation of a specific undefined tag is 
reported. 


User Action: Either define the undefined tags, or correct the spelling of the 
tag being invoked. The undefined tags were reported in other messages. 


UPDATINFO, Update page label string, <tagname> 


Informational: A document that is being processed to produce update pages 
may have associated update information. The information indicated will be 
printed on the bottom of each page output. 


User Action: Verify that the update page label is correct for your document. 


USER_IMSG, string 
Line is number of file filename 


Informational: This message code is used for messages written to the 
terminal or output stream when a <USER_I_MESSAGE> tag is specified in 
the input file. 


User Action: The action you take depends on the content of the user’s 
message. 


USER_WMSG, | at tag or text on line n of file 
file-spec 
string 


Warning: This message code is used for messages written to the terminal or 
output stream when a <USER_W_MESSAGE> tag is specified in the input file. 


User Action: The action you take depends on the content of the user’s 
message. 


USETAGDEF, Using tag’s default: number 


Informational: This informational message accompanies other warning 
messages. It generally indicates that a default value is being taken. 


User Action: Edit the SDML source file to correct the argument. 
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VBARINARG, | at tag or text on line n of file 
file-spec 
A vertical bar was found in argument number to tag <tagname> 
Use the <VBAR> tag to code a vertical bar in an argument 


Fatal: The tag translator treats the vertical bar character as a special operator 
character in arguments to tags. If you include a vertical bar character in 

an argument, the tag translator may overlook the right parenthesis that 
terminates the argument list, and may scan all of the remaining input looking 
for the proper terminator. 


If you have mistakenly omitted the closing parenthesis of an argument list, 
the tag translator begins to search the remainder of your file for a closing 
parenthesis. If it encounters a vertical bar (perhaps in a figure or code 
example), it then begins to search for a matching ampersand. Thus, this error 
message may be issued instead of the EOFARGLST error message. 


User Action: Correct the argument list by replacing the vertical bar with the 
<VBAR> tag, or by properly closing the argument list. 


VMOVREFLOW, _§ at tag or text on line 1 of file 
file-spec . 
Internal error. Failure to allocate additional space in virtual 
memory 


Fatal: This error message is generally caused by one of two types of error in 
the SDML file. These errors, and the action that you should take to correct 
them are as follows: 


e An unterminated argument list. If you fail to terminate an argument list, 
the tag translator regards the text that follows the argument list as part of 
the last argument. Suppose you write 


<EMPHASIS>(always\BOLD> press the RETURN key. 
instead of 
<EMPHASIS>(always\BOLD) press the RETURN key. 


The tag translator does not realize that the right angle bracket should 
have been a right parenthesis. It tries to include all the following words 
as part of the second argument of the <EMPHASIS> tag. This means 
that it may store large portions of the SDML file in memory while it 
searches for a closing parenthesis to the argument list. If memory limits 
are exceeded, the VMOVRFLOW error message is issued. 


e Too many tag definitions. The tag translator has no limit on the number 
of tag definitions. However, a limit is imposed by the memory allocation 
algorithm. When this limit is exceeded, it usually indicates that one or 
both of the following conditions are present: 


— A file that contains tag definitions is being repeatedly included. This 
file is often a global definitions file that is being used to define tags 
or symbols for text substitution. You can avoid memory limitation 
problems by using the <CHECK_FOR_INCLUSION> tag at the start of 
such a file. This ensures that the file’s definitions are actually loaded 
only once, even though the file is included many times. 
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— A tag’s definition changes frequently during execution, perhaps 
when the tag is being used to temporarily hold a text string. If the 
tag’s definition is established each time by the <DEFINE> tag rather 
than by the <REDEFINE> tag, the definitions pile up in memory. A 
reference to the tag always retrieves the latest definition, and if you 
never use the <UNDEFINE> tag to erase the latest definition, you will 
never see the old definitions, but they are still occupying memory 
space. 


User Action: Determine if the error was caused by an unclosed argument 
list. The error is generally located by the information supplied in the error 
message. 


Otherwise, examine your tag definitions to determine whether you are 
defining the same tag name multiple times. You can avoid memory limitation 
problems by defining your tags with the <REDEFINE> tag, rather than the 
<DEFINE> tag. Unless you specifically intend to “stack” tag definitions, 

and use the <UNDEFINE> tag to “pop” definitions off the stack, you should 
always establish a tag definition with the <REDEFINE> tag. 


XRFINCMPL, at tag or text on line n of file 
file-spec 
The file containing cross reference symbols is incomplete 
filename 


Fatal: During the reading of the file containing cross reference symbols, an 
error was detected that indicates that the file was not recorded correctly. 


User Action: Submit a Software Performance Report. 


XRFNOREMM, | at tag or text on line n of file 
file-spec 
The temporary cross reference file cannot be renamed to 
filename 


Fatal: The tag translator creates a temporary cross reference file with a file 
type TMP. When the file is complete, it renames it with a file type XREF. The 
rename operation has failed. 


User Action: Submit a Software Performance Report. 
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Text Processor Messages 
ATPT, Font was read at number pt 
Informational: This is an internal error. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADALPHA , Improper alphabetic constant 
Warning: Text formatter expected to scan a constant consisting only of letters. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADCHAR , Text line contains an invalid character 
Warning: Text formatter could not scan a character from current input line. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADCODE , Bad code number: value, must be between smaller number and larger 
number 
using zero instead 


Warning: Text formatter expected to find code value within range shown. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADCS , Bad control sequence: ‘Command’ 


Warning: Text formatter could not understand how user meant to use the 
shown command in the current context. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADDISC , Improper discretionary list. Must contain only 
‘kerns’ and ‘boxes’ 


Warning: Discretionary list contained unexpected information. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 
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BADDISCMATH , Illegal ‘discretionary break’ in ‘math’ mode. 
The third part of a discretionary break must be empty 
in this mode. Attempting to recover... 


Warning: Discretionary break was improperly coded. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADDUMP , Cannot ’\dump’ inside a group 


Warning: Command ’\dump’ occurred when there was one group or more 
still active. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADFONTFMT , Fatal font format file error 


Error: Text formatter could not load the font format file, or the font format 
file was fatally flawed. . 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADFRACTION , Ambiguous fraction ignored. 
Warning: Text formatter could not determine the meaning of a fraction. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADGLUE , Infinite glue. Attempting to recover 


Warning: Text formatter was asked to typeset a box using infinite glue. Glue 
was made finite and text formatter attempted to continue. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADHALIGN , Improper ’\halign’ 
Warning: Command ’\halign’ was invalid in current context. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADHRULE , Cannot use ’‘\hrule’ in an ’\hbox’. 
Use ’\leaders’ or ’\hrulefill’ instead 


Warning: Command ‘\hrule’ is invalid in current context. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 
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BADHYPHEN , Improper \hypenation ignored. 
Must contain only letters and hyphens 


Warning: Text formatter can only read letters and hyphens in a hyphenation 
pattern. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADHYPHFMT , Fatal hyphenation format file error 


Error: Text formatter could not load the hyphenation format file, or the 
hyphenation format file was fatally flawed. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADLASTBOX , ’\box255’ is not empty, attempting to continue 


Warning: Text formatter expected ’\box255’ to be empty. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADLEADERS ,_ ‘\leaders’ not followed by proper ‘glue’ 
Warning: Glue specification was not valid in current context. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADLETINPAT , Non-letter found in ‘\patterns’ 
Warning: Text formatter can only read letters in a ‘pattern’. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADLIMIT , Ignoring misplaced ’\limits’ or ’\nolimits’ command 


Warning: Text formatter did not expect to see ’\limits’ or ’\nolimits’ in this 
context. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADMACROFMT , Fatal macro format file error 


Error: Text formatter could not load the macro format file, or the macro 
format file was fatally flawed. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


| Messages 
Text Processor Messages 


BADMAG , Illegal magnification ratio: bad number, value set to good number 
Warning: Text formatter could not set magnification to requested value. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADMATHCHAR , ‘font’ number font-number is missing this character: ‘character’ 


Warning: Text formatter could not type set the character shown, because that 
character was missing from the font shown. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADMATHDELIM , Inserted missing or misplaced math delimiter 
Warning: Text formatter became confused while closing a math formula. 


User Action: Check the SDML file for <MATH> sequences and verify that 
all parentheses are matched and that all math tags and delimiters are correctly 
terminated. If this does not correct the problem and you are under a service 
contract with Digital, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADNOALIGN , ’\noalign’ can only appear after ’\cr’ 
Warning: Command ‘\noalign’ is not valid in current context. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADOMIT, ‘\omit’ can only appear after ’\cr’ or ’&’ 
Warning: Command ’\omit’ is not valid in current context. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADOUTLOOP, Output loop repeated number of cycles times without doing a 
‘\shipout’ 
Attempting to recover. Increase ’\maxdeadcycles’ if neccesary 


Warning: Text formatter cycled through its output loop too many times 
without doing a ’\shipout’. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADPARAMNUM , Illegal parameter number 


Warning: Text formatter became confused while scanning parameters to a 
macro. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 
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BADPARAMSEQ ,_ Parameter was numbered out of sequence 


Warning: Text formatter became confused while scanning parameters to a 
macro because a parameter was numbered out of sequence. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADPATTERNS , Bad \patterns 
Warning: Text formatter became confused while reading a ‘pattern’. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADPREAMBLE , Cannot nest alignment preambles 


Error: Text formatter became confused during current alignment, because it 
found an alignment within an alignment. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADPREFIX2, Can’t use ’\long’ or ‘\outer’ with ‘command’ 


Warning: Text formatter will ignore ’\long’ or ’\outer’ or ’\global’ when used 
with the shown command. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADPREFIX3 , Can’t use ’\long’ or ’\outer’ or ’\global’ with ‘command’ 


Warning: Text formatter will ignore ’\long’ or ’\outer’ when used with the 
shown command. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADPREVGRAF , ‘’\prevgraf’ = number . Value must be positive 


Warning: Text formatter expected to see ’\prevgraf’ specified with a positive 
value. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a - 
Software Performance Report. 


BADPT , Bad font size = number pt, replaced by 10 pt 
Warning: Text formatter attempted to read a font at an improper font size. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 
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BADUNBOX, Cannot ’unbox’ a ‘hbox or vbox’ in ‘Text formatter mode’ mode 
Warning: Command ‘unbox’ is invalid under current circumstances. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADUNIT , Bad unit of measure, replaced by ’string’ 


Warning: Text formatter could not use the unit of measure user asked for. 
Unit was changed to shown value. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADVALUE , ‘quantity’ = number. Value must be between smaller number and 
larger number 


Warning: Text formatter was expecting to read a value within the range 
shown. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call. your customer service center. Otherwise, submit a 
Software Performance Report. 


BUFFERSIZE , Maximum number of characters in the input buffer is number 
Informational: User has exceeded total size of text formatter’s input buffer. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


CANNOTRESETMAG , Cannot change magnification, using old value: number 
Warning: Text formatter can only set magnification value once. _ 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


CONFUSION , Text formatter became confused doing this: ‘Command’, . 
job is aborting 


Error: Text formatter became confused doing the shown activity, and had t 
exit. | 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


DIMENTOOBIG , Dimension too large 


Warning: Text formatter became confused while scanning a dimension, 
because the dimension was too big. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 
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DISCTOOLONG Discretionary list is too long. Attempting to recover 
Warning: Discretionary list was too long. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer-service center. Otherwise, submit a 
Software Performance Report. 


DOUBLESUB ,_ Double subscript 


Warning: Text formatter found a quantity with two subscripts. In these cases, 
x"1*2 will be treated like x*1{}*2. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


DOUBLESUPER , Double superscript 


Warning: Text formatter found a quantity with two superscripts. In these 
cases, x__1_2 will be treated like x_1{}_2. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


DURING ,_ Error occurred during a ‘command’ 
Warning: Error occurred during a specified command or control sequence. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


DURINGOR , Error occurred during a ‘command’ or ‘command’ 


Warning: Error occurred during one of the two commands or control 
sequences shown. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call.your customer service center. Otherwise, submit a 
Software Performance Report. 


EMERGENCYSTOP , Job is aborting 
Error: Text formatter became hopelessly confused, and must exit. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


ENDDURING , ‘\end’ occurred during ‘command’ 
Warning: The command ’\end’ occurred unexpectedly. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 
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ENDINGROUP , \end’ occurred inside group at level number 


Warning: The command ‘\end’ occurred when there was one group or more 
still active. Examine the input and output files and attempt to determine what 
tag was not terminated. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


EOF , Unexpected end of file 


Warning: Text formatter encountered the end of the current file 
unexpectedly. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


EOP, Paragraph ended before the following completed: 
Warning: Text formatter encountered the end of a paragraph unexpectedly. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


EXTRATAB, Extra ’\halign’ or ’&’ in alignment has been changed to ‘\cr’ 
Warning: Text formatter found extra or unexpected ’\halign’ or ’&’. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


FILENAME ,  ‘file-name’ 
Informational: Identifies current file being used as input. 


User Action: This message always occurs in conjunction with other messages. 
Action depends upon associated message. 


FONTDIMEN , The following font has only number fontdimen parameters 
. To increase the number of font parameters you must use 
\fontdimen immediately after the \font is loaded 


Warning: The current font has too many parameters. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


FONTERROR , Error occurred in the following font: 
Warning: Text formatter found an error in the current font. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 
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FONTMEMSIZE , Font memory size = number words 
Informational: Reports the total size of text formatter’s font memory. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


FONTTYPE , Font was declared by: ‘string’ 
Warning: Identifies the font’s type, e.g. \preloaded. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


FUNNYCS, Missing control sequence inserted 
Warning: Text formatter became confused while defining a control sequence. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


IDENT , _ string 
Informational: Identifies the current version of the text formatter. 


User Action: None. 


IGNORED ,_ Extra ‘command’ ignored 
Warning: An unneccesary text formatting command was found. 


- User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


IGNOREDTEXT , All text was ignored after line string 
Warning: Text formatter could not typeset any of the following line shown. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


IGNORING ,._ Ignored the following: ‘command’ 
Warning: Text formatter encountered an unexpected command, and ignored 
it. 
User Action: If you receive this message and are under a service contract 


with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


IMPROPERCMD , Improper command found: ‘command’ 
Warning’ Command shown is not valid in current context. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 
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INCOMPLETECMD , Incomplete command found: ‘command’ 


Warning: Text formatter became confused while trying to scan the shown 
command. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


INFO ,_ text—on page number 


Informational: A text formatting macro has generated an informational 
message. A problem occurred while the text formatter was processing the 
output. text provides a description of the problem. In most cases, the file 
will continue processing successfully and you can examine the output. The 
message indicates the page on which the problem occurred, and you can use 
this information to correct the problem. 


User Action: The following is a list of the messages you may see and the 
associated action that will correct the problem. 


¢ Callout number 0 undefined. Using 1. 
A <CALLOUT> or <CO> tag was specified as 0. 
e Callout number exceeds 99. Using 99. 


A. <CALLOUT> or <CO> tag’s value is greater than 99. POSTSCRIPT 
output devices cannot print numbers greater than 99. 


e Error in setting note type; using default. 


A local or personal DESIGN file specified an invalid value for the 
\noteformattype. Refer to the VAX DOCUMENT Doctype Designer’s 
Guide for value values. 


e Error. Maximum number of table footnotes exceeded. 


Too many <FOOTNOTE> tags were specified for a table. The largest 
number that is allowed is 12. 


e Error pushing/popping revision bars. 


<MARK> and <ENDMARK> tags are not evenly matched, or are not 
suppressed around heading levels in the correct sequence. If you receive 
this message and are under a service contract with DIGITAL, call your 
customer service center. Otherwise, submit a Software Performance 
Report. 


¢ Possible problem in output of revision bars. 


The text formatter encountered a complex situation while a revision mark 
(from the <MARK> tag) was active. Examine your output closely to 
determine if the revision mark output is correct. A revision mark may not 
appear, or appear where you did not intend it to. If there is a problem, 
you can change your source file to decrease the range in which a revision 
mark is active. For example, if you have changes in two rows of a table, 
you might place the <MARK> and <ENDMARK> tags inside each of the 
two <TABLE_ROW> tags instead of around the entire table. 
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Figure is too large for a single page. 


A value specified in <FIGURE_SPACE> or <FIGURE_FILE> exceeds the 
depth of the output page. The text formatter will use only the depth of 
the page. 


Correct the invalid depth argument in the SDML file. 
<FOOTREF> before <FOOTNOTE> in table ignored. 


A tag <FOOTREF> tag occurred in a table for which no corresponding 
<FOOTNOTE> tag occured. Footnotes in tables must be specified at the 
beginning of the table, before any references to them occur. 


Graphics files cannot be included on this device. 


A <FIGURE_FILE> or <ICON_FILE> tag was encountered that specified 
a graphics file to be included on a device that does not support the 
inclusion of graphics. The tag is ignored. 


Index subentry more than 4 levels deep; ignored. 


An indexing tag (<x> or <yY>) contained more than four 
<XSUBENTRY> tags. Only four levels of subentry are allowed. 


Correct the indexing tag to remove the excessive subentries. 
Included files are not allowed to float. 


An included text formatter file in a figure is assumed to be multipage and 
cannot float. 


Remove the FLOAT attribute. 

Internal error while processing a table. 

The text formatter has received bad input. Submit an SPR. 
Invalid table of contents entry 


A local or personal doctype specified an invalid value for a table of 
contents entry. Correct the table of contents entry to use a valid code. 


If this error occurs using a standard VAX DOCUMENT design, submit an 
SPR. 


Monospaced example is too big to keep. 


The keyword KEEP was specified as an attribute to a <CODE_EXAMPLE> 
tag or other tag that specifies a monospaced example. The number of 
lines in the example cannot fit on a single page of output. 


Remove the keyword KEEP from the tag and provide <VALID_BREAK> 
tags to indicate acceptable page break points. 


Multipage figure won't be allowed to float. 


A figure was specified with both the attributes FLOAT and MULTIPAGE. 
Multipage figures cannot float; the text processor will output it at the 
location of its occurrence in the source file. 


Remove the FLOAT attribute. 


No template heading defined at this level; using level two. 
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<PAGE> ignored in floating figure. 


A <PAGE> or <FINAL_CLEANUP> (PAGE) tag was encountered in a figure 
that had the default attribute float. 


Specify <FIGURE_ATTRIBUTES> (MULTIPAGE) for all figures that are more 
than a page in length. 


<PAGE> tag ignored in table that is not multipage. 


A <PAGE> or <FINAL_CLEANUP> (PAGE) tag was encountered in a table 
that had the default attribute float. 


Specify <TABLE_ATTRIBUTES> (MULTIPAGE) for all tables that are more 


than a page in length. 


Possible table paging problem. 


A table that is output on more than one page is being forced to break 
across pages without explicit page breaking or sufficient valid table break 
points. 


_In most cases, the output will be perfectly all right. The text formatter 


makes its best decision about breaking tables across pages when there are 
<TABLE_ROW_BREAK> tags to specify the first and last valid breaks for 
the table. 


Revision bars cannot be output on this device. 


<REVISION> , <MARK>, and <ENDMARK> tags cannot be processed for 
this device. No change bars will be printed. 


<SPAN> at end of table column ignored. 


The <SPAN> tag, which specifies that text is to span 2 or more columns 
in a table, must precede the text in the argument. For example, 


<TABLE_ROW>(<SPAN>(3)This text sits across all three columns) 
Move the <SPAN> tag to the beginning of the tag’s argument. 
The table, as specified, is too wide for the page. 


The values specified in <TABLE_SETUP> result in a table that will not 
fit on the current page. Recheck the arguments you specified to the 
_<TABLE_SETUP> tag, and decrease them. You will be able to tell from 
the output how much of the table is excessive. 


<TABLE_HEADS> preceding <TABLE_SETUP> ignored. 


Table headings must be specified following the <TABLE_SETUP> tag. 
Move the <TABLE_HEADS> so that it precedes the <TABLE_SETUP> tag. 


<TABLE_HEADS> within <TABLE_UNIT> ignored. 


The <TABLE_HEADS> should not be used inside <TABLE_UNIT> 
sequences; use the <TABLE_UNIT_HEADS> tag instead. 


<TABLE_ROW> encountered outside of a <TABLE>. 


A <TABLE_ROW> tag was specified, but there was no <TABLE> tag. The 
tag will be ignored. Correct the file so that a valid <TABLE> tag precedes 
it. 
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¢  <TABLE_ROW_BREAK> tags in single-page table ignored. 


The tag <TABLE_ROW_BREAK> was specified in a table that had the 
attribute KEEP specified. 


Remove the KEEP attribute from the table or remove the <TABLE_ROW_ 
BREAK> tag. 


¢ <TABLE_UNIT_HEADS> outside of table unit ignored. 


A <TABLE_UNIT_HEADS> tag was encountered before a <TABLE_UNIT> 
tag was specified to begin a table unit. 


_ Remove the tag; or insert a <TABLE_UNIT> tag to enclose a table unit. 
e Tracing is disabled in VAX DOCUMENT. 


An instruction to accumulate tracing information occurred in a TEX file. 
VAX DOCUMENT does not support these instructions. 


e Too many columns specified for multi-column output. 
A local or personal doctype specified too many columns of output. 


If this error occurs using a standard doctype, submit an SPR. 


INITEXPAT , ‘\patterns’ can only be used by Initex 


Warning: Text formatter only recognizes ’\patterns’ when it is building 
format files, not during a run of VAX DOCUMENT. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


INSERTED , Missing ‘command’ inserted 


Warning: A missing command was inserted into input stream. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


INSERTHBOX , ’\insert’ can only be added to a ’\vbox’ 


Warning: Command ‘\insert’ is not valid in current context. 


User Action: If you receive this message and are under a service contract | 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


INSERTING , Inserting ‘command’ 


Warning: Text formatter attempted to resolve an unexpected situation by 
inserting shown command into input stream. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 
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INSUFEXTFON , Math formula deleted: Insufficient ‘extension’ fonts 


Warning: Math formula could not be typeset because ‘extension’ fonts were 
inadequate or missing. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


INSUFSYMFON , Math formula deleted: Insufficient ‘symbol’ fonts 


Warning: Math formula could not be typeset because ‘symbol’ fonts were 
inadequate or missing. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


INTERNALERROR , Internal error number: ‘error number’. Job is aborting 
Error: Text formatter found an internal inconsistency. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


LINE ,_ Error occurred on or around line number: number 


Informational: Reports the current line of input that the text formatter is 
processing. 


User Action: This message always occurs in conjuction with other messages. 
Action depends upon associated message. 


LINETOOLONG , Line too long by Integer.remainder points 
Informational: The text formatter found an overly lengthy line. 


User Action: This message always occurs in conjuction with other messages. 
Action depends upon associated message. 


LINETOOSHORT , Line too short—on page Page number 
Informational: The text formatter found a line that was too short. 


User Action: This message always occurs in conjuction with other messages. 
Action depends upon associated message. 


MATHOVERFLOW , Arithmetic overflow 
Warning; The result of a mathematical operation was too large. 


User Action: If you receive this message and are under a service contract. 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


MAXFONTS , Maximum number of fonts is: number 
Informational: User has exceeded maximum number of fonts. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 
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MAXGROUPS , Maximum number of groups is: number 
Informational: User has exceeded maximum number of groups. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


MAXHASH , Maximum number of entries in hash table is: number 


Informational: User has exceeded maximum number of entries on text 
formatter’s hash table. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


MAXHYPHS , Number of hyphenation exceptions is: number 
Informational: User has exceeded maximum number of hyphenations. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


MAXINPUTS , Maximum number of simultaneous input files is: number 


Informational: User has exceeded maximum number of simultaneous input 
files. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


MAXNESTS , Maximum number of simultaneous semantic levels is number 


Informational: User has exceeded maximum number of simultaneous 
semantic levels in text formatter. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


MAXPARAMS ; Maximum number of simultaneous text macro parameters is 
number 


Informational: User has exceeded maximum number of parameters to a 
macro. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


MAXSAVE , Maximum number of entries on save stack is: number 


Informational: User has exceeded maximum number of entries on text 
formatter’s save stack. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 
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MAXSTRINGS , Maximum number of strings is: number 
Informational: User has exceeded maximum number of strings. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


MEMORYSIZE , Main memory size = number words 
Informational: User has exceeded total size of text formatter’s main memory. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


MESSAGE , _ text—on page number 


Warning: A text formatter macro generated a warning message. The 
following is a list of possible messages and actions. 


User Action: See the action associated with each of the following messages. 
e Error in window size. 


An error occurred in a local or personal doctype; an invalid value was 
specified in a \window. 


If this error occurs in a standard doctype, submit an SPR. 
e Internal error in setting blockindents. 


Too many arguments were specified to \blockindents, or the values were 
not valid. This error should only occur if a local or personal DESIGN file 
contains an invalid value. : 


e Internal error in figure key definition. 
Submit an SPR. 
¢ Too many floating figures. 


There are too many <FIGURE> tag sequences within a short span of text 
specified, and the default attribute “float” is in effect for all of them. 


The text formatter cannot produce meaningful output when there are too 
many figures that are floating. When you have a large number of figures 
in a short span of text, you should use the <FIGURE_ATTRIBUTES> (KEEP) 

tag to keep them in sequential order. 


¢ No room for a new [item]. 


Internal use. 


MISSINGBOOL , ’ <’ or =’ or’>’ 
Warning: Text formatter expected to scan one of the boolean values shown. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. Determine which boolean value is needed 
and insert it in the right place. 
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MISSINGLBRACE , Possible missing ’{’ 
_ Warning: Text formatter did not see an ’{’. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


MISSINGRBRACE , Possible missing ’}’ 
Warning: Text formatter did not see an ’)’. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


MODE , Error occurred in ‘string’ mode’ 
Informational: Reports the current mode that the text formatter is in. 


User Action: This message always occurs in conjunction with other messages. 
Action depends upon associated message. 


MUERROR , Mismatched glue units. Assuming that 1mu=1pt 
Warning: Text formatter scanned glue specifications that are incompatible. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


NOBOX, Expected to find ‘\hbox’ or ’\vbox’ or 
‘\copy’ or ’\box’ or something like that. 
Some text may be missing from output. 


Warning: Text formatter expected to find a box. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


NOEND ,_ No ’\end’ was found | 
Error: Text formatter expected to see a ’\end’ command. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


NOFONTID , Could not find font identifier for the following font: 
Warning: Font identifier for current font is missing. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


C—60 


Messages 
Text Processor Messages 


NOINSLASTBOX , ’\insert255’ is illegal. Changing to ’\insert0’ 


Warning: Text formatter register ’\insert255’ cannot be used in current 
context. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


NOMATHACCENT , Changed ’\accent’ to ’\mathaccent’ 


Warning: The text formatter command ’\accent’ works differently in formulas 
than it does in normal text. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


NONUMBER, Missing number, using zero 
Warning: Text formatter expected to find a number. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


NOROOM , Exceeded memory capacity: 


Error: Text formatter exceeded one of its memory capacities. The message 
immediately following indicates which quantity was exceeded. 


User Action: If you receive this message and are under a service contract 
-with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


NOUSEAFTER , After this: ‘command.’, the following is invalid: 


Warning: Text formatter cannot use the command shown in the next message 
directly after the command shown in this message. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


NUMBERTOOBIG , Number too large, using 2147483647 instead 


Warning: Text formatter could not use specified number because it is too big. 
Text formatter used 2147483647 instead, which is the largest number possible 
in that context. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


ONEOFFOUR , Some or all of the following 4 messages apply: 


Warning: One or more of the four messages that follow on your screen’ 
apply. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 
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ONEOFTWO , One or both of the following messages apply: 
Warning: One or both of the two messages that follow on your screen apply. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


ONPAGE , on page number 
Informational: Identifies the current page being output. 


User Action: This message always occurs in conjunction with other messages. 
Action depends upon associated message. 


OUTFILENAME ,  ‘file-name’ 
Informational: Identifies the output file name. 


User Action: None. 


PAGESOUT , number page(s) written. 
Informational: Reports the. number of pages written to the output file. 


User Action: None. 


PAGETOOBIG , Cannot ship out huge page. More than 18 feet wide or long. 


Warning: Text formatter became confused during typesetting of current page 
because page was too large. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


PAGETOOLONG , Page too long by string.string points 


Warning: Text formatter could not fit contents of current page into 
boundaries of current page. Such errors are common with a line printer 
because it is monospaced. 


User Action: Examine output on page shown to determine if there is a 
problem with the coding of the SDML file. Ignore the problem if it is not 
serious. You also have the options of changing destinations or changing the 
DOCTYPE, if possible. 


PAGETOOSHORT , Page too short—on page Page number 


Informational: The text formatter had trouble composing the current page. 
There were not enough lines to reach the bottom. Such errors are common 
with a line printer because it is monospaced. 


User Action: Examine output on page shown to determine if there is a 
problem with the coding of the SDML file. Ignore the problem if it is not 
serious. You also have the options of changing destinations or changing the 
DOCTYPE, if possible. 
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PATTERNEXISTS , Duplicate ‘pattern’ found 
Warning: Text formatter found a duplicate ‘pattern’. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


PATTERNMEMSIZE , Hyphenation pattern memory size = number words 


Informational: User has exceeded total size of text formatter’s hyphenation 
memory. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


POOLSIZE , String memory size = number bytes 
Informational: User has exceeded total size of text formatter’s string memory. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


RUNAWAY , Runaway ‘kind of text’ 


Warning: Text formatter became confused while scanning the shown kind of 
text. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


SCALED , Font was scaled: “number 
Informational: This is an internal error. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


SHOWCONTEXT , ‘text’ 


Informational: Displays input stream that the text formatter was attempting 
to read when something went wrong. 


User Action: This message always occurs in conjunction with other messages. 
Action depends upon associated message. 


SHOWTOKEN , ‘text’ 
Informational: Displays part of text formatter’s current token list. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


C-63 


Messages 
Text Processor Messages 


TIGHTSPACING , Insufficient inter-word spacing—on page Page number 


Informational: The text formatter had trouble composing a line—there was 
not enough white space on the line. Such errors are common with a line 
printer because it is monospaced. 


User Action: Examine output on page shown to determine if there is a 
problem with the coding of the SDML file. Ignore the problem if it is not 
serious. You also have the options of changing destinations or changing the 
DOCTYPE, if possible. 


TOOFEWLINES , Excess inter-line spacing—on page Page number 


Informational: The text formatter had trouble composing the current page. 
There was too much white space between the lines. Such errors are common 
with a line printer because it is monospaced. 


User Action: Examine output on page shown to determine if there is a 
problem with the coding of the SDML file. Ignore the problem if it is not 
serious. You also have the options of changing destinations or changing the 
DOCTYPE, if possible. 


TOOMANYERRORS, Error limit is 30 
Error: Text formatter found more than 30 errors. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


TOOMANYLINES , Insufficient inter-word spacing—on page Page number 


Informational: The text formatter had trouble composing the current page. 
There was not enough white space between the lines. Such errors are 
common with a line printer because it is monospaced. 


User Action: Examine output on page shown to determine if there is a 
problem with the coding of the SDML file. Ignore the problem if it is not 
serious. You also have the options of changing destinations or changing the 
DOCTYPE, if possible. 


TOOMANYPARAMS , More than nine parameters were passed to a macro 


Warning: Text formatter became confused while scanning parameters to a 
macro because there were too many parameters. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


TRACE , text 


Informational: User has turned on text formatter’s tracing mechanism. Text 
contains information about VAX DOCUMENT’s text formatter’s internals. 


User Action: None. 
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UNDEFINEDCS , Undefined control sequence 
Warning: Text formatter encountered an undefined control sequence. 


User Action: This can happen if a TEX file, created using one doctype, is 
reprocessed using another doctype; for example, if you created a TEX file 
using the LETTER doctype then reprocessed the file using /NOTAG and the 
OVERHEADS doctype. Reprocess the file using /TAG_TRANSLATORT and 
/TEXT_FORMATTER. If you receive this message and are under a service 
contract with DIGITAL, call your customer service center. Otherwise, submit 
a Software Performance Report. 


UNKNOWNUNIT , Dimension unit must be: em,ex,in,pt,pc,cm,mm,dd,cc,bp,sp 
Warning: Text formatter expected to read one of the dimensions shown. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


USINGZERO , Bad ‘value’, must be between smaller number and larger number, 
using zero instead 


Warning: Text formatter expected to scan a value in the range shown. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


VSPLITHBOX , Attempted to ’\vsplit’ a “\hbox’ 
Warning: Command ‘\vsplit’ is not valid in current context. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


WIDESPACING , Excess inter-word spacing—on page Page number 


Informational: The text formatter had trouble composing a line; there was 
too much white space on the line. Such errors are common with a line printer 
because it is monospaced. 


User Action: Examine output on page shown to determine if there is a 
problem with the coding of the SDML file. Ignore the problem if it is not 
serious. You also have the options of changing destinations or changing the 
DOCTYPE, if possible. 
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BADFILABORT , file bad—aborting run 


Error: The device converter cannot use the font file named in an adjacent 
message. 


User Action: Another file may have been given the same name. Use the 
DIRECTORY/FULL DCL command to see that the size and format are similar 
to other font files. If necessary, reinstall the font data. 

BADFONT , font file bad—using blanks 


Warning: The file that describes the font design is unusable. The program 
will substitute blanks for the characters in this font. 


_ User Action: Use the DIRECTORY/FULL DCL command to see if the size 
and format of this file resembles other font files. If necessary, reinstall the 
font data. 


BADINCLUDE , included file is bad 


Warning: The program has encountered errors in processing the contents or 
index file requested. 


User Action: Check that previous processing steps generated the contents or 
index file expected; this may be an old, incompatible file, it may be another 
file with the same name, or it may be the correct file made unreadable 
because of an I/O error. : 


BADMETRIC , bad metric file 


Error: The device converter has encountered errors in processing the 
indicated font metric file. 


User Action: This may be another file named the same; check the file size 
and format with the DIRECTORY/FULL DCL command to see if it resembles 
other font metric files. It may be necessary to reinstall the font data. 


CANNOTCONNECT , cannot connect along a diagonal 


Warning: While attempting to draw change bars, the program has 
encountered an attempt to draw a non-vertical line. Only vertical change 
bars are allowed. 


User Action: This is controlled by the macros that describe change bar 
positioning. Look there for errors and inconsistencies. 


CANNOTCREATE , cannot create output file 
Error: The program cannot create an output file. 


User Action: Check that the output directory exists, that the user has 
permission to write in it, and that the device is available and is not full. 


CANNOTOPEN , cannot open input file 
Error: The program cannot open the input DVI file. 


User Action: Check that the input directory exists; check that the file exists 
or was created by earlier processing steps; check that the user has permission 
to read the file, and that the device is available. 
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CONFIGERROR , error in configuration file 


Error: An error has been detected in reading the file that describes PostScript 
fonts. An adjacent error message gives more details. 


User Action: Check that the device is available and that the user has 
permission to read the file. Take the action suggested by the adjacent error 
message. If necessary, reinstall the font data. 


FILENESTING , one included file cannot include another file 
Warning: One contents or index file may not include another. 


User Action: Check the macros that describe contents and index files to see 
that they are correctly generating the filespecs; see if the filespec generated 
for the contents or index file is the same as an existing file. 


FONTCONKFIG , font description missing or illegal in configuration file 


Error: The specified font is not present, or not fully described, in the file that 
describes PostScript fonts. 


User Action: If necessary, reinstall the PostScript support. 


FONTERROR , error in font 
string 


Warning: An error has occurred while processing the named font. The 
specific problem is identified in an adjacent message. 


User Action: Note the name of the font. Take the action suggested by the 
adjacent error message. 


FONTTOOBIG , too many characters in font—limit is 188 
Error: The document uses too many characters from the named font. 


User Action: Reinstall the font files. If problem persists, and if you are under 
a service contract with Digital, call your customer service center. Otherwise, 
submit a software performance report (SPR). 


IDENT , string 
Informational: Reports the version of the program in use. 
User Action: None. 

IGNORING , ignoring included input file 
filespec 


Warning: The program cannot process the included DVI file for the reason 
specified in an adjacent message. 


User Action: Note the name of the file. Take the action suggested by the 
adjacent error message. 


INCLUDING , including input file: 
filespec 


Informational: Reports that the program is processing a DVI file other than 
the file named on the command line; this is typically a contents or index file. 


User Action: None. 
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INPUTBAD , bad input file—aborting run 


Error: The program has encountered errors in the named input file and 
cannot continue. 


User Action: Check the messages generated by earlier processing steps to see 
if a complete DVI file was created. 


INPUTFILE , input file is: 
filespec 


Informational: Reports the name of the primary DVI file; i.e., the file named 
on the command line. . 


User Action: None. 


INTERNALERROR , internal error 
Error: A problem internal to the device converter prevents it from continuing. 


User Action: This sometimes represents a document so large or complex 
that it exceeds internal buffer sizes; sometimes you can work around this by 
running contents and index processing as separate jobs, rather than including 
them in place. You may be able to process the document in two or more 
pieces by using the STARTING_PAGE and ENDING-PAGE or NUMBER 
OF_PAGES parameters to the device converter. If you receive this message 
and are under a service contract with DIGITAL, call your customer service 
center. Otherwise, submit a Software Performance Report. 


INVALIDPOINT , invalid point number ‘number’ 


Warning: An error has occurred in the macros used to describe change bars. 
Specifically, an attempt has been made to locate a point off the page, or the 
point is incorrectly described. 


User Action: This is controlled by the macros that describe change bar 
positioning. Look there for errors and inconsistencies. 


NOFILABORT , cannot open file—aborting run 
Error: The device converter cannot open the named file. 


User Action: Check to see that the device is available, that the file exists, and 
that the user has privileges to access that file. 


NOFONT, cannot open font file—using blanks 
Warning: The device converter cannot open the named font file. 


User Action: Check that the device exists and is available, and that the user 
has permission to read the file. 


NOINCLUDE , cannot open included file 


Warning: The device converter cannot open the contents or index file named 
in the adjacent message. Either the pathname and filename are incorrect, 

or the program cannot gain access because of file protection or locking by 
another process. Processing will continue without this file. 


User Action: Check that the named file exists and that the user has access to 
it. 
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NOINPUTPAGE , no pages in input file 


Error: The input file named in an adjacent message contains no pages; 
therefore, there will be no output to print. 


User Action: Check to see if errors reported in earlier processes caused there 
to be no pages generated. 
NOMETRIC , cannot open metric file 


Error: The font metric file named in an adjacent message doesn’t exist, or the 
user does not have access to it because of file protection or problems with the 
device. 


User Action: Check that the file exists and is available, and that the user has 
access ta it. Check that the user is specifying a DVI input file appropriate for 
the destination requested. 

NOSIXELIMAGE , cannot find sixel image in figure file 


Warning: The figure file named in an adjacent message does not contain the 
command sequence that identifies a sixel image. White space appears where 
the figure is expected. 


User Action: Check the figure file. For LN03 use, it must be a sixel file. 


NOSUBSTITUTE , no adequate alternate font found 


Error: The text formatter has requested a down-loaded font for which the 
device converter cannot find a reasonable substitute.. 


User Action: Check the document design. for the fonts used; check that the 
corresponding font files exist at the sizes desired. 
NOSUCHUNIT , no such unit of measure 


Warning: A DVI special command used to position change bars or describe 
graphics files contains an unknown unit of measure, or no unit at all. 


User Action: This is controlled by the macros that describe change bar 
positioning or figure file characteristics. Look there for errors. 
OFFPAGE , cannot set text outside page boundaries 


Warning: An attempt has been made to set text outside the boundaries of the 
physical page specified. 


User Action: Check the messages from the text formatter for lines too long; 
check that you specified a destination that can print a page as large as 
required by your design; check to see if you specified a horizontal or vertical, 
offset that will push your design off the page. 


ONPAGE , on page [string] 
Informational: Reports the number of the output page on which the 


condition reported in the associated messages occurred. 


User Action: Note this page number if you need to refer to the output. 
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OUTPUTFAIL , error writing to output file 


Error: The program encountered an error in writing to the output file. This 
usually means that the output disk is full, the user’s disk quota is exceeded, 
or the output disk has become unusable. 


User Action: Check that the output device is usable. If the disk is full or 
the user’s disk quota is used up, delete unwanted files and run the device 
converter again. 


PAGENOTFOUND , starting page not found 


Error: The user has specified a starting page number, but that page does not 
exist in the input file. 


User Action: Check the starting page specified; check the input file specified. 


PAGESOUT , number page(s) written to file: 
filespec 


Informational: This reports the number of pages written to the output file 
named. 


User Action: No direct action needed; however, if the number is zero, or less 
than expected, check other messages for errors or examine the commands, 
filespecs, options, and input files for problems. 


PAGETOOCOMPLEX ,_ cannot hold all font data—using blanks 


Warning: The amount of font data required to describe all the characters 
on this page will not fit in the LN03 font memory, so the characters in the 
current font will be represented as blanks. 


User Action: If using a design that allows you to change textsize, choose 
a smaller size; or use only one kind of emphasis on the page if possible; or 
move portions of the text to adjacent pages. 


PLOTFILEFAIL , cannot open figure file 


Warning: The program cannot find the figure file named, or can find it but 
cannot open it. 


User Action: Check that you have specified the right filespec, that the 

file exists in the path specified (or current default directory, if no path is 
specified), that you have permission to read that file, and that the file is not 
locked by the action of some other program running at the same time. 


PROLOGERROR , error in prolog file 


Error: The device converter cannot read its file that contains the PostScript 
prolog for output. 


User Action: Check that the device is available, that the file exists, and that 
the user has privileges to access the file. If necessary, reinstall the PostScript 
support. 
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PROLOGERROR , error in prolog file 


Error: The device converter cannot read its file that contains the PostScript 
prolog for output. 


User Action: Check that the device is available, that the file exists, and that 
the user has privileges to access the file. If necessary, reinstall the PostScript 
support. 


SPECIALERROR , error in \special 
string 


Warning: This lists the text of a DVI special command as received by the 
device converter. This command is generated by macros, but may contain 
some user-specified information, such as a filespec or size. The specific 
problem associated with this special will be described in an adjacent message. 


User Action: Consult the adjacent message for a description of the problem. 
If necessary, check this message for a filespec or size that may have been 
incorrectly entered in a tag describing a figure file, contents file, or index file. 


SPECTOOLONG , \special too long—will try to process anyway 


Warning: This DVI special command exceeds the maximum length of 1000 
characters. The program will truncate the command and try to process it. 


User Action: Check the macros that generate this special command— 
they may be appending too many spaces or extraneous text following the 
command. 


TOOMANYDVI, too many included input files 
Warning: Too many included contents or index files have been requested. 
User Action: Remove excess contents_file and index_file tags from input 
file. 

TOOMANYFONTS , too many fonts—limit is 100 
Error: The document contains too many fonts. 


User Action: Change the document design so it does not require so many 
fonts, or use SDML tags that do not require so many fonts, or break 

the document into separate documents, or process the contents or index 
separately. 


TOOMANYGLYPHS , too many glyphs used in all fonts combined 


Error: The document contains too many characters in too many fonts. The 
LNO3 cannot hold this many characters. 


User Action: Break the device conversion of this document into two or more 
jobs, specifying the starting page and ending page or number of pages. End 
one job before the page on which this error was reported. 
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UNRECOGOPTN , unrecognized option 


Warning: This DVI special command contains an option not supported by 
this device converter, or the program cannot find an option at all. 


User Action: Check to see if you have requested a figure file, contents 
file, index file, change bars, or other function which is not supported for 
this destination; check for errors in the macros that generate this special 
command. 
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C.5 Index Facility Messages 
ARGLST_TOO_LONG , The argument list is too long, or is not terminated. 
Error: An error occurred when the indexer read your INX file. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


ATRLST_INVALID , The attribute list is not validly constructed. 
Error: An error occurred when the indexer read your INX file. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADLOGIC , internal logic error detected 
Error: The INDEX utility has detected an internal failure. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADVALUE , _ ’string’ is an invalid keyword value 
Error: The indicated string is not a valid keyword value. 


User Action: Reprocess the input file specifying a correct value for the 
qualifier keyword. 


BEGIN_QUOTE ,, Needs a” character or a ’ character to begin string. 
Error: An error occurred when the indexer read your INX file. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


CANT_CREATE_BRN , Can't create intermediate file 
Error: A necessary intermediate file cannot be created. 


User Action: Check to be sure your INX file has not been corrupted, that 
you have sufficient disk space, that you have access to the current directory, 
and that there are no other factors in your current environment that would 
prevent the creation of a file during processing. 


CREATED , string’ created 
Success: The indicated output file has been created. 
User Action: None. 

CUT_PAGE_-PREFIX , Page prefix was truncated to string. 
Warning: A page prefix is greater then eight characters. 


User Action: If truncation is not accepted, change the prefix to eight 
characters or less in the INX file and resubmit. 
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DUPBEGIN , duplicate BEGIN attribute ignored. 
Warning: A BEGIN was encountered within the scope of another BEGIN. 


User Action: Check the index entries in your source file to be sure that 
BEGIN’s and END’s match. 


EMPTYIN , empty intermediate input file. 
Warning: The intermediate work file is empty. 


User Action: Check the command line to be sure that the input file was 
spelled correctly. 


ENDPASS_1, End of first pass over the input. 


Informational: Indicates that the INDEX utility has started processing the 
input file. 


User Action: None. 
ENDPASS_2, End of second pass over the input. 
Success: The indexing utility has completed processing the input file. 


User Action: None. 


END_QUOTE_1, Needs a’ character to end string. 
Error: An error occurred when the indexer read your INX file. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


END_QUOTE_2, Needs a” character to end string. 
Error: An error occurred when the indexer read your INX file. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


IDENT , _ string 


Informational: Indicates the version of the INDEX utility. This message is 
produced by specifying the /IDENTIFICATION qualifier. 


User Action: None. 


IGNORED ,_ ’string’ ignored 


Warning: The indicated command line qualifier or qualifier keyword was 
ignored. One or more messages follow to indicate the reason. 


User Action: See the explanation in the error messages that follow on your 
screen. 
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INPUT_OVERFLOW , Overflowed input put-back stack; element too large. 
Error: An error occurred when the indexer read your INX file. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


INSVIRMEM , insufficient virtual memory 


Error: The INDEX utility does not have sufficient virtual memory to generate 
the index. 


User Action: Either reduce the size of the index or increase the SYSGEN 
parameter, VIRTUALPAGECNT, reboot, and reprocess your file. 


INVINPUT , invalid input file format for intermediate file. 


Warning: The intermediate input file is not compatible with the INDEX 
utility. It may have been corrupted. 


User Action: Reprocess to get a new file. 


INVRECORD , invalid record type in intermediate file. 


Warning: The intermediate input file is not compatible with the INDEX 
utility. It may have been corrupted. 


User Action: Reprocess to get a new file. 


LANG_IGNORED , LANGUAGE tag not at beginning of file—being ignored. 


Warning: The language tag was encountered in the INX file after index entry 
processing has started. 


User Action: Reposition the language tag to the start of the INX file. 


LANG_NAME , The string language name is not valid. 
Fatal: The language specified is not supported. 


User Action: Modify the language tag in the INX file to specify Danish, 
English, Finnish, French, German, Italian, Norwegian, Portuguese, Spanish, 
or Swedish. 


NEEDS_START , Needs a = character in front of the string. 
Error: An error occurred when the indexer read your INX file. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


NOBEGIN , END attribute ignored; no corresponding BEGIN. 


Warning: An END was encountered and no previous BEGIN was 
encountered. 


User Action: Check the index entries in your source file to be sure BEGIN’s 
and END’s match. 
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NOBRN , error converting ‘string’. to internal file 


Error: The indicated input file was not converted to an internal index 
workfile. 


User Action: Correct any problems noted by the file conversion routine. 


NOEND , BEGIN has no corresponding END 
Warning: A BEGIN was encountered and the matching END was not. 


User Action: Check the index entries in your source file to be sure BEGIN’s 
and END’s match. 


NOINDEX , no index information in intermediate file. 
Warning: No index information was found in the intermediate work file. 


User Action: Check your input file to see if it includes any index entries. 


tee, 
ne, 
ed 


NOLIST , parameter list not allowed — 


Warning: More than one file was specified on a line of a master index options 
file. 


User Action: Modify the options file so that it contains only one name on 
each line. 


NOREF , page reference not found 
Error: An internal logic error was detected. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


NOT_UNDELIM_STR, Not an undelimited string. 
Error: An error occurred when the indexer read your INX file. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
‘Software Performance Report. 


NO_ARGLST , string tag not followed by a starting argument list. 
Error: An error occurred when the indexer read your INX file. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


NO_ENTRY_BLOCK , Attribute build failure—no entry block built. 
Error: An error occurred when the indexer read your INX file. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 
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OPENIN , error opening ‘filename’ for input 


Error: The input file is erroneous, the file does not exist, or you do not have 
access to the file. 


User Action: Check the file specification for errors and check to see if you 
have access to the file. 


OPENOUT , error opening ’string’ for output 


Error: An output file cannot be opened. This message is usually accompanied 
by a VAX RMS message indicating the reason for the failure. 


User Action: Take corrective action based on the associated message. 


PAGENUMBER, Illegal page number. 
Error: An error occurred when the indexer read your INX file. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


SECTION_NAME, The string section name is not valid. 
Error: The indicated section name is not CHAPTER, PREFIX or APPENDIX. 


User Action: Change the section name in the INX file and resubmit. 


SKIPPED , 1 reference(s) inside page range—ignored 


Warning: The INDEX utility detected n index entries inside a BEGIN/END 
page range. These entries were ignored. 


User Action: Check the input file to be sure that the BEGIN and END are 
positioned properly. If so, remove the intervening index entries. 


SYNTAX, error parsing ‘string’ 


Warning: The indicated string encountered during the processing of a master 
index options file is erroneous. One or more messages follow indicating the 
nature of the error. 


User Action: See the description in the messages that follow on your screen. 


TEXT , string 


Informational: This messages follows other error messages that are generated 
when an error in a master index file or text processor character file is detected. 
It shows the full line of the options file that was in error. It is accompanied 
by one or more other error messages. 


User Action: See the action for the acompanying error messages on your 
screen. 


TEXTD , entry text: ‘string’ 


Informational: This message follows other messages generated due to some 
error in an index entry. It shows the complete text of the index entry. 


User Action: See the action for the acompanying error messages on your 
screen. : 
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TOKEN—OVERFLOW , A token is more than string characters long. 
Error: A control string is more than the indicated length. 


User Action: Check the item reported and modify the INX file for proper 
format. 


TOODEEP , maximum subindex depth exceeded 


‘Warning: An index entry containing ten or more levels of subindexing was 
detected. The subindexing was ignored. 


User Action: Generate index entries with fewer levels of subindexing. 


TRUNCATED , string too long—truncated 


Warning: A character string is too large to fit into an INDEX utility internal 
buffer. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


VALERR , specified value is out of legal range 
Error: This message is part of a compound message. 


User Action: Look at the associated messages for an indication of what is out 
of range. 


WHERE , in string tag on line number of the INX file. 
Informational: Locates the error. 


User Action: See the action for the accompanying error messages on your 
screen. 


WHERE , in string tag on line number of the INX file. 
Informational: Locates the error. 


User Action: See the action for the accompanying error messages on your 
screen. 


D Summary of VAX DOCUMENT Tags 


Table D-1 provides an alphabetic list of the tags that VAX DOCUMENT 
recognizes. For each tag, the doctype is given. The doctype is shown in the 
table as Global or as one of the doctypes. 


If the doctype is specified as Global, the tag is recognized in all doctypes.! 
Global tags are described in VAX DOCUMENT User Manual, Volume 1. 


If the doctype listed is one of the standard doctypes, the tag is recognized 
only for that doctype and is described in VAX DOCUMENT User Manual, 


Volume 2. 


Table D—1 Summary of VAX DOCUMENT Tags 


Tag Doctype 
<ABSTRACT> ARTICLE 
<ABSTRACT> Global 
<ACCENT> Global 
<ACKNOWLEDGMENTS> ARTICLE 
<ALIGN_AFTER> Global 
<ALIGN_CHAR> Global 
< ALIGN NUMBER> Global 
<AMPERSAND> Global 
<APPENDIX> Global 
<ARGDEF> SOFTWARE 
<ARGDEFLIST> SOFTWARE 
<ARGITEM> SOFTWARE 
<ARGTEXT> SOFTWARE 
<ARGUMENT> SOFTWARE 
<AUTHOR> ARTICLE 


Description 


Creates an article abstract and can also specify a 
heading for that abstract. 


Begins a summary description of a document on 
the title page or part page of a document. 


Supplies a freestanding accent mark. 
Creates an acknowledgments section in an article. 
Allows you to position formatted text in a list. 


Identifies a nonprinting character to be used to 
align numeric information within a column of a list 
or table. 


Specifies a numeric value with alignment 
characters. 


Supplies an ampersand within an argument to a 
tag or in math. . 


Begins an appendix. 


Begins the text that defines an item in an 
argument definition list. 


Begins a definition list describing zero or more 
routine arguments. 


Labels one to seven routine argument items to be 
defined in an argument definition list outside of 
the Routine template, or a single routine argument 
and its attributes within the Routine template. 


Labels definition text in an argument definition list 
which replaces the information contained in a pair 
of <ARGITEM> and <ARGDEF> tags. 


Emphasizes an argument name within text. 
Specifies an author of an article. 


1 A few exceptions to this rule are noted in the introductions to the doctypes in VAX DOCUMENT User Manual, Volume 2. 
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Tag 
<AUTHOR> 


<AUTHOR> 


<AUTHOR_ADDR> 


<AUTHOR_AFF> 


<AUTHOR_INFO> 


<AUTHOR_LIST> 


<AUTO_NUMBER> 


<BACKSLASH> 
<BACK_NOTE> 


<BACK_NOTES> 
<BIBLIOGRAPHY > 
<BIB_ENTRY> 
<BOX> 


<BYLINE> 
<BYLINE> 
<CALLOUT> 


<CALLOUTS> 


<CALLOUT_REF> 
<CC> 


<CCLIST > 


<CENTER_LINE> 


Doctype 
REPORT 


SOFTWARE 


ARTICLE 


ARTICLE 


OVERHEADS 


ARTICLE 


OVERHEADS 


Global 
ARTICLE 


ARTICLE 
ARTICLE 
ARTICLE 
Global 


REPORT 


‘SOFTWARE 


Global 


Global 


Global 
LETTER 


LETTER 


Global 


Description 


Places the name of an author and one or two 
additional lines of information about the author in 
the front matter portion of a document. 


Places the name of an author and one or two 
additional lines of information about the author in 
the front matter portion of a document. 


Specifies the address of the author. 


Specifies information about the organizational 
affiliation of the author. 


Specifies informational text about the overhead 
presentation. 


Creates a list of authors for an article with 
multiple authors. 


Specifies that slides are to be numbered 
automatically, and that the slide number is to be 
placed at the bottom of every slide. Optionally, 
specifies a text string to be placed in front of the 
slide number on each page. 


Supplies a backslash within an argument to a tag. 


Creates a back note entry, and creates a 
superscript reference number in the article text. 


Causes any accumulated back notes to be output. 
Begins a bibliography. 
Specifies a single entry in a bibliography. 


Produces a box that surrounds a user-specified 
character string. 


Places a name and other optional information 
below a ruled line in a signature list. 

Places a name and other optional information 
below a ruled line in a signature list. 

Labels a callout in an example. The <CALLOUT> 
tag is identical to the <CO> tag. 

Labels the beginning of a series of callouts 
contained in an example and enables the use 
of the <CALLOUT> and <CO> tags. (The 
<CALLOUT> tag is equivalent to the <CO> 
tag.) 

Labels a reference to a callout in text. 


Lists the name of someone who is to receive a 
copy of a memo or letter. 


Begins a list of persons to whom you want to 
send a copy of a memo or letter. 


Specifies a line of text that is to be centered in 


the current text margin. 


Summary of VAX DOCUMENT Tags 


Table D—1 (Cont.) Summary of VAX DOCUMENT Tags 


Tag 
<CHAPTER> 
<CHEAD> 


<CHEAD> 
<CHEAD> 


<CHECK_FOR_INCLUSION> 


<CLOSING> 
<CO> 


<CODE_EXAMPLE> 


-<<COLUMN> 
<COLUMN> 


<COMMAND> 
<COMMAND_SECTION> 


<COMMENT > 


<CONDITION> 


<CONSTRUCT > 


<CONSTRUCT_LIST > 


<CONTENTS_FILE> 


<COPYRIGHT_DATE> 


<COPYRIGHT_PAGE> 


<CP> 


Doctype 


Global 
Global 


LETTER 
REPORT 
Global 


LETTER 
Global 


Global 


ARTICLE 


REPORT 


SOFTWARE 
SOFTWARE 


Global 


Global 


SOFTWARE 


SOFTWARE 


Global 


Global 


Global 


Global 


Description 


Begins a chapter. 


Marks an unnumbered centered heading. Similar 
to the <CENTER> tag. 


Creates a centered heading. 
Creates a centered heading. 


Marks a file to ensure the file is included only 
once in the output. 


Specifies the closing of a letter. 


Labels a callout in an example. The <CO> tag is 
identical to the <CALLOUT> tag. 


Begins an example of code. Code consists 
of words or lines of instructions written in a 
programming language or a command language. 


Specifies that a new column of output should 
begin in a two-column doctype. 


Specifies that a new column of output should 
begin in a two-column doctype. 


Begins a new command description. 


Begins a command reference section, enables 
tags reserved for use in command sections, and 
sets paging attributes. 


Marks a portion of your SDML input file that 
you do not want to appear in your output. Text 
marked by a <COMMENT> tag is ignored by the 
tag translator during processing. 


Marks a section of an SDML file that is not 
processed unless one of the arguments to 
the tag matches the argument in the related 
<SET_CONDITION> tag. 


Specifies a variable construct and gives its 
expansion. 


Begins a list of construct items and definitions 
that expand on variables specified in the context 
of the <STATEMENT_FORMAT> tag. 


Specifies that the table of contents output file 
for a document should be included when the 
document is processed. 


Inserts a copyright date line on the copyright 
page along with other system-specific copyright 
information. 


Begins a copyright page and enables copyright 
page tags. 

Marks the continuation of a paragraph that has 
been interrupted by another text element. 
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Tag 
<CPAREN> 


<CPOS> 
<DATE> 
<DEFINE_BOOK_NAME> 


<DEFINE_SYMBOL> 


<DEFINITION_LIST > 
<DEFINITION_LIST_HEAD> 
<DEFLIST_DEF> 


<DEFLIST_ITEM> 
<DELETE_KEY > 


<DESCRIPTION> 


<DISPLAY > 

<DISTLIST > 

<DOCTYPE> 
<DOCUMENT_ATTRIBUTES> 
<DOCUMENT_ATTRIBUTES> 


<DOCUMENT_ATTRIBUTES> 


<EMPHASIS> 


<ENDCOPYRIGHT_PAGE> 


<ENDPART_PAGE> 


<ENDTITLE_PAGE> 


Doctype 
Global 


SOFTWARE 
Global 
Global 


Global 


Global 
Global 
Global 


Global 
SOFTWARE 


SOFTWARE 


SOFTWARE 
LETTER 
Global 
ARTICLE 
REPORT 


SOFTWARE 


Global 


Global 


Global 


Global 


Description 


Supplies an unmatched closing parenthesis in an 
argument to a tag. 


Marks the cursor position in a screen display. 
Produces the current system date or time. 


Defines the title of a book and associates a 
user-defined symbol-name with that title for later 
reference. 


Associates a string of text with a user-defined 
symbol, so that the text can be referenced via 
this symbol throughout the document. 


Begins a definition list. 


Supplies the heading to precede a definition 
list. Output formatting is controlled by the 
document-type. 


Begins the text that defines an item in a definition 
list. 


Marks an item to be defined in a definition list. 


Creates a special character resembling a DELETE 
key on a keyboard. 


Begins a section of descriptive text providing 
detailed information on the current reference 
element. 


Simulates the appearance and position of 
characters on a terminal screen. 


Begins a list of persons to whom you want to 
distribute a memo or letter. 


Specifies the document type for your file. This 
tag is for informational purposes, only. 


Enables doctype-specific tags that override the 
default design format of the ARTICLE doctype. 


Enables doctype-specific tags that override the 
default design format of the REPORT doctype. 


Enables doctype-specific tags that override 
the default design format of the SOFTWARE 
doctype. 


Marks a word or phrase for distinctive 
typographical treatment. 


Terminates the copyright page and optionally 
provides text that may be used on a document- 
type specific basis. 


Terminates a part page and optionally specifies 
paging attributes for text that follows. 


Terminates a title page and cptionally specifies 
text to appear at the bottom of the title page. 
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Tag Doctype Description 

<EXAMPLE> Global Labels the beginning of a formal example. 

<EXAMPLES_INTRO> SOFTWARE Provides introductory text before an example. 

<EXAMPLE_ATTRIBUTES> Global Specifies attributes for the current example. 

<EXAMPLE_FILE> Global Causes a separate file containing an example to 

. be included in the source file. 

<EXAMPLE_SEQUENCE> SOFTWARE Begins a numbered sequence of informal 
examples. 

<EXAMPLE_SPACE> Global Leaves space for an example that will be pasted 
in during final production. 

<EXC> SOFTWARE Begins a code example within a series of 
numbered informal examples. . 

<EXI> SOFTWARE Begins an interactive example within a series of 

numbered informal examples. 

<EXTEXT> SOFTWARE Terminates an example and begins an explanation 
in a sequence of numbered examples. 

<FARG> SOFTWARE Adds a single argument line to a list of arguments 
in a routine syntax format section. 

<FARGS> SOFTWARE Provides the argument portion of a routine syntax 
statement within the context of the <FORMAT> 
tag. 

<FCMD> Global Specifies the keyword portion of a formatted 
command/parameter pair in a format section. 

<FCMD> . SOFTWARE Identifies a command or statement keyword, 
and an optional parameter list, within a format 
‘section. 

<FFUNC> SOFTWARE Labels a function within the context of a 
<FORMAT> or <STATEMENT_FORMAT> tag 
section. 

<FIGURE> Global Labels the beginning of a figure. 

<FIGURE_ATTRIBUTES> Global Specifies the placement of a figure on the page. 
Also specifies valid page breaks for that figure. 

<FIGURE_FILE> Global Includes a graphics file in your output file if the 
output device has graphics capability. 

<FIGURE_SPACE> Global _Marks the space required for a figure that will be 
pasted in during final production. 

<FINAL_CLEANUP > Global Provides explicit formatting instructions for the 
text formatter to be used for final formatting and 
cleanup. 

<FOOTNOTE> Global Places a footnote character in text, using the 


character specified in the tag’s argument, and 
places the footnote text at the bottom of the 
page. 

<FOOTNOTE_TEXT> Global Specifies the text of a footnote associated with a 
footnote reference. 
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Tag Doctype Description 

<FOOTREF> Global Creates one or more footnote callouts in text 
or in a table using the footnote numbers or 
characters as arguments. 

<FORMAT> Global Enables <FCMD>, <FPARMS>, and <FPARM> 
to distinguish formatted command keywords and 
parameters. 

<FORMAT> SOFTWARE Begins a section that highlights the syntax of a 
tag, command, or routine, including keywords 
and arguments. 

<FORMAT_SUBHEAD> SOFTWARE Introduces one of the multiple formats in the 
statement format section. 

<FPARM> Global Specifies a parameter to be formatted following 
<FPARMS> , aligned under the parameter list 
portion of a keyword/parameter list pair. 

<FPARM> SOFTWARE Adds a single parameter line to a list of 
parameters in a command or statement syntax 
format section. 

<FPARMS> Global Specifies the parameter portion of a formatted 
command/parameter pair in a format section. 

<FPARMS> SOFTWARE Specifies the parameters to a command or 

. statement keyword. 
<FROM_ADDRESS> LETTER Specifies the name and address of the sender of 
: a letter, and places this information flush left near 

the right margin. 

<FRONT_MATTER> Global Begins the front matter of a book. 

<FRTN> SOFTWARE Specifies the routine-keyword portion of a routine 
syntax statement within the context of the 
<FORMAT> tag. 

<FTAG> SOFTWARE Specifies the name of a tag and its arguments 
within the context of a <FORMAT> tag. 

<FUNCTION> SOFTWARE Begins a new function description. 

<GDEF> Global Begins the text that defines a term in a glossary. 

<GLOSSARY> Global Begins a glossary of terms in a document or 
book. 

<GRAPHIC> SOFTWARE Displays terminal graphics characters. 

<GREF> Global Marks a cross-reference to a term within a 
glossary. 

<GTERM> Globa! Labels a term to be defined in a glossary. 

<HEAD> LETTER Creates a main heading which is placed on the 
left side of the page. 

<HEAD> REPORT Creates a main heading which is placed on the 
left of the output page. 

<HEADx> Global Marks a heading of the level specified (1 through 


6). 
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Tag 
<HELLIPSIS> 
<HYPHENATE> 


<ICON> 


<ICON_FILE> 


<ICON_TEXT> 


<INCLUDE> 
<INCLUDES_FILE> 


<INDEX _FILE> 
<INTERACTIVE> 


<INTRO_SUBTITLE> 
<INTRO_TITLE> 


<KEEP> 


<KEY> 

<KEYPAD> 
<KEYPAD_ENDROW> 
<KEYPAD_ROW> 


<KEYPAD_SECTION> 
<KEYWORD> 


<KEY_NAME> 
<KEY_PLUS> 


Doctype 


Global 
Global 


Global 


Global 


Global 


Global 
Global 


Global 


~ Global 


OVERHEADS 


OVERHEADS 


Global 


SOFTWARE 


SOFTWARE 


SOFTWARE 


SOFTWARE 


SOFTWARE 
Global 


SOFTWARE 
SOFTWARE 


Description 


Labels omitted material in a horizontal dotted line. 


Provides information about legal hyphenation of a 
word of text. 


Allows you to include a graphic image in your 
printed output and print text parallel to the image. 
The text is printed either to the right or left of the 
picture. 


Specifies a graphics file that accompanies text 
within the <ICON> and <ENDICON> tags. 


Labels the text that accompanies a graphic image 
included in text with the <ICON> and <END_ 
ICON> tags. 


Causes the contents of a specified file to be 
included in the current input file for processing. 


Equates a logical name with a file specification 
during processing of a profile. 


Specifies the position in a book (or document) 
where an index file should be included in the 
output. 


Begins an example dialog between user and 
system and enables the tags <S> and <U> to 
distinguish system text from user text. 


Creates a secondary title of up to four lines on an 
introductory slide. 


Creates a main title of up to four lines on an 
introductory slide. 


Specifies that a string of text should always occur 
on the same line of output, that is, should not be 
hyphenated between lines. 


Depicts a key from a keyboard or keypad 
graphically. 


Specifies an individual keypad diagram and 
optionally supplies a title for that diagram. 


Displays the bottom row of an editing keypad 
that has up to three keys. 


Displays a row of an editing keypad that has up 
to four keys. 


Begins a series of one or more keypad diagrams. 


Labels a significant word that deserves to be 
distinguished typographically. 


Emphasizes the name of a key within text. 


Creates a plus sign between keys in a key 
sequence example. 
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Tag Doctype Description 

<KEY_SEQUENCE> SOFTWARE Begins a section containing one or more key 
representations. 

<KEY_TYPE> SOFTWARE Provides a descriptive label for keys within a key 
sequence. 

<LE> Global Labels a list element. 

<LEVEL> REPORT Specifies an outline entry and the organizational 
level of that outline entry. 

<LINE> Global Specifies that the text that follows is to be placed 
on a new line of output. 

<LINE_ART> Global Labels a rough sketch produced at the terminal 


keyboard for draft output, to give some idea of 
what the final figure will look like. 


<LIST> Global Begins a list. The type of list (for example, 
numbered or stacked) is specified by the 
argument to the <LIST> tag. 


<LITERAL> Global Allows you to specify text that contains words 
in angle brackets that might otherwise be 
interpreted as tags. 


<LOWERCASE> Global Labels text that should appear as lowercase in 
the final output. 

<MARK> Global Indicates the beginning of new or modified 
information. 

<MARK_DELETION> ; Global Marks a place from which information has been 
deleted from a previously published version of a 
document. 

<MATH> Global Labels a short mathematical expression or the 
beginning of an extended mathematical example. 

<MATH_—CHAR> Global Creates a special mathematical symbol. 

<MCS> Global Labels a character in the DEC Multinational — 
Character Set. 

<MEMO_DATE> LETTER Creates a line in a memo or letter that displays 
the date after the heading “Date:” 

<MEMO_FROM> LETTER Identifies the name and address of the sender of 


a memo, and places this information flush left on 
the left margin, with a heading of “From:” 


<MEMO_HEADER> LETTER Centers the heading “Interoffice Memorandum” in 
bold letters on the current output line. 
<MEMO_LINE> LETTER Lets you create your own titled informational 
lines. 
<MEMO_TO> LETTER Specifies the name and address of the receiver of 


a memo, and places this information flush left on 
the left margin, with a heading of “To:.” 


<MESSAGE_SECTION> SOFTWARE Begins a section of error message descriptions. 
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Tag 
<MESSAGE_TYPE> 
<MSG> 
<MSGS> 
< MSG_TEXT> 
<NESTED_TABLE_BREAK> 


<NEWTERM> 
<NOTE> 


<OPAREN> 

~ <ORDER_NUMBER> 
<OUTLINE> 
<OVERVIEW> 


<P> 
<PAGE> 


<PARAMDEF> 
<PARAMDEFLIST > 
<PARAMITEM> 
<PARENDCHAR> 
<PART> 
<PART_PAGE> 


<PREFACE> 


Doctype 
SOFTWARE 


SOFTWARE 


SOFTWARE 


SOFTWARE 


Global 


Global 


Global 


Global 


Global 


REPORT 


SOFTWARE 


Global 
Global 


SOFTWARE 


SOFTWARE 


SOFTWARE 


Global 


Global 


Global 


Global 


Description 


Establishes the format for error messages and 
affects the numbers of arguments passed to the 
<MSG> and <MSGS> tags. 


Formats the text of a message within a series of 
error message descriptions. 


Formats the text of one or more messages within 
a series of error message descriptions. 


Labels text which describes a message in a 
<MESSAGE_SECTION> tag section. 


Marks a place that a nested table may be broken 
across pages. 


Labels a term first introduced into the text in 
order to emphasize the term. In output, the term 
will be italicized. 


Labels a note, caution, warning, or some other 
portion of text to which you wish to draw 
attention. 


Supplies an unmatched opening parenthesis in an 
argument to a tag. : 


Labels the order number or part number that may 
appear on the title page of a book. 


Begins an outline and specifies a title for the 
outline. 


Provides a summary description of a reference 
element. 


Marks the beginning of a new paragraph. 


Breaks a page of text, forcing the text that 
follows the tag to begin on a new page. 


Begins the text that defines an item in a 
parameter definition list. 


Begins a definition list describing zero or more 
parameters or arguments. 


Labels one to seven items to be defined in a 
parameter definition list. 


Labels a character that will appear alone within 
parentheses to achieve better spacing. 


Labels the start of a major division within a 
document, and starts it on a new page. 


Begins a divider page for a new part of a 
document. 


Labels the beginning of a preface. 
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Tag Doctype Description 

<PREFACE_SECTION> Global Creates a major section in the preface of a 
book, to contain information such as a summary 
of changes to the book or other relevant 
information. 

<PRINT_DATE> Global Inserts a print date line on the copyright page. 

<PROFILE> Global Indicates that the source file is a profile and that 
a bookbuild is to be performed. 

<PROMPT> SOFTWARE Identifies a prompt which appears on a separate 
line from other prompts, and any parameters 
associated with that prompt. 

<PROMPTS> SOFTWARE Begins a summary of interactive prompts. 

<QPAIR> SOFTWARE Labels a qualifier pair within a qualifier format list. 

<QUALDEF> SOFTWARE Begins the text that defines an item in a qualifier 
definition list. 

<QUALDEFLIST> SOFTWARE Begins a definition list describing zero or more 
command qualifiers. 

<QUALITEM> SOFTWARE Labels one to seven items to be defined in a 
qualifier definition list. 

<QUAL_LIST> SOFTWARE Begins a qualifier summary list. 

<QUAL_LIST_DEFAULT_HEADS> SOFTWARE Modifies the default heading used by the 
<QUAL_LIST> tag. 

<QUAL_LIST_HEADS > SOFTWARE Labels the headings you want to use for one or 
both of the columns in a qualifier format list when 
<QUAL_LIST> (SPECIAL) is used in unusual cases 
for formatting control. 

<QUOTATION> ARTICLE Begins a quotation in which the spacing is 
retained and the text is not filled or justified. 

<QUOTE> Global Labels quoted material in the output. 

<REFERENCE > Global Makes a reference to a symbol-name in a book 
element or text element. When processed, 
<REFERENCE> is replaced with the current value 
of the symbol-name. 

<REF_NOTE> ARTICLE Specifies the text of a reference note, and creates 
a bracketed reference number in the article text. 

<REF_NOTES> ARTICLE Causes all accumulated reference notes to be 
output. 

<RELATED_ITEM> SOFTWARE Provides a text description of a set of tags or the 
usage of a set of tags that may be related to the 
tag being described. 

<RELATED_TAG> SOFTWARE Specifies a single tag that is related to the current 
tag. 

<RELATED_TAGS> SOFTWARE Provides a summary of tags whose usage is 
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Tag 
<RESTRICTIONS > 


<RETTEXT> 
<RETURNS> 
<RETURN_VALUE> 
<REVISION> 


<REVISION_INFO> 


<RIGHT_LINE> 


<RITEM> 

<ROUTINE> 
<ROUTINE_SECTION> 
<RSDEFLIST > 


<RSITEM> 


<RULE> 
<RUNNING_FEET > 
<RUNNING_FEET > 


<RUNNING_FEET > 
<RUNNING_TITLE> 


<RUNNING_TITLE> 
<RUNNING_TITLE> 
<S> 


<SALUTATION> 
<SAMPLE_TEXT> 
<SDML_TAG> 
<SECTION> 


Doctype 
SOFTWARE 


SOFTWARE 
SOFTWARE 
SOFTWARE 
Global 


Global 


Global 


SOFTWARE 
SOFTWARE 
SOFTWARE 
SOFTWARE 


SOFTWARE 


Global 
ARTICLE 
OVERHEADS 


REPORT 
ARTICLE 


OVERHEADS 
REPORT 
Global 


LETTER 
Global 
SOFTWARE 
REPORT 


Description 
Labels the restrictions on the use of a reference 
element within a SOFTWARE reference template. 


Provides general information about the attributes 
of the value returned by the routine. 


Provides information about the value returned by 
a routine. 


Labels a character string return value. 


Indicates that the document contains either new 
or modified information and enables the output of 
the <MARK> tag. 


Labels a section on a title page that provides 
information on what previous books have been 
superseded by the current one. 


Specifies a line of text that is to be right-adjusted 
in the current text margin. 


Labels an item in a list of restrictions. 
Begins a new routine description. 


Begins a routine reference section, enables tags 
reserved for use in routine sections, and sets 
paging attributes. 


Begins a return status definition list in the routine 
template. 


Specifies the return status value of a routine and 
lists its meaning. 


Outputs a rule within a table. 
Creates a heading at the bottom of each page. 


Specifies text to be placed at the bottom of the 
next slide and all subsequent slides. 


Creates a heading at the bottom of each page. 


Creates a one or two line running heading at the 
top of each page. 


Specifies text to be placed at the top of the next 
slide and all subsequent slides. 


Creates a one or two line running heading at the 
top of each page. 


Labels the system portion of a dialog between 
user and system in an interactive example. 


Specifies the salutation for the letter. 
Distinguishes, typographically, an extract of text. 
Begins a new tag description. 


Begins a new page and creates a major heading 
on the left side of that page. 
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Tag 
<SET_APPENDIX _LETTER> 


<SET_APPENDIX _NUMBER> 
<SET_CHAPTER_NUMBER> 


<SET_CONDITION> 
<SET_TEMPLATE_COMMAND> 


<SET_TEMPLATE_HEADING> 
<SET_TEMPLATE_LIST> 
<SET_TEMPLATE_PARA> 


<SET_TEMPLATE_ROUTINE> 
<SET_TEMPLATE_STATEMENT > 


<SET_TEMPLATE_— 
SUBCOMMAND> 


<SET_TEMPLATE_TABLE> 
<SET_TEMPLATE_TAG> 
<SHOW-_LEVELS> 
<SIGNATURES > 
<SIGNATURES> 


<SIGNATURE_LINE> 
<SIGNATURE_LIST > 


<SINGLE_QUOTE> 


<SLIDE> 
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Doctype 
Global 


MILSPEC 
Global 


Global 
SOFTWARE 


SOFTWARE 
SOFTWARE 
SOFTWARE 


SOFTWARE 


SOFTWARE 


SOFTWARE 


SOFTWARE 
SOFTWARE 
REPORT 
REPORT 
SOFTWARE 


MILSPEC 


MILSPEC 


Global 


OVERHEADS 


Description 


Overrides the default appendix letter assigned to 
an appendix by VAX DOCUMENT. 


Overrides the default appendix roman number 
assigned to an appendix by VAX DOCUMENT. 


Overrides the default chapter number assigned to 
a chapter by VAX DOCUMENT. 


Creates or removes a condition-name. 


Defines a new tag with the same function as the 
<COMMAND> tag, and changes the format of 
command descriptions produced using the new 
tag. 

Overrides the heading for all subsequent uses of 
a template tag. 


Creates a user-defined set of tags for listing 
information. 


Defines a set of template tags for setting the 
format of a paragraph of information. 


Defines a new reference element tag name to 
use in the routine template, and specifies the 
formatting attributes for the new tag. 


Defines a new reference element tag name to 
use in the statement template, and specifies the 
formatting attributes for the new tag. 


Changes the name of the <SUBCOMMAND> tag 
to the name you specify, and specifies formatting 
attributes for the new tag. 


Defines a set of template tags for setting 
information in two- or three-column lists. 


Defines a new reference element tag name to 
use in the tag template, and specifies formatting 
attributes for the newly-defined tag. 


Emphasizes text within an outline. 


Begins a list of signatures which are to appear. in 
the front matter of a document. 


Begins a list of signatures which are to appear in 
the front matter of a document. 


Creates up to two rules on a line and places a 
name below each rule; each rule is used as a 
signatory line for the person listed below it. 


Begins a two-column listing of signature lines 
on the title page of a document and supplies 
headings for each of those columns. 


Outputs, within text, a single quotation mark as it 
appears on a keyboard. 


Begins a new overhead slide. 
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Tag 
<SOURCE_NOTE> 


<SPECIAL _CHAR> 


<SPECIFICATION_INFO> 


<SPEC_TITLE> 


<STATEMENT > 


<STATEMENT_FORMAT > 


<STATEMENT_LINE> 


<STATEMENT_SECTION> 


<SUBCOMMAND> 
<SUBCOMMAND_SECTION> 


<SUBCOMMAND_SECTION— 
HEAD> 


<SUBHEADx> 
<SUBJECT > 


<SUBTITLE> 
<SUBTITLE> 


<SUBTITLE> 
<SYNTAX> 


<SYNTAX_DEFAULT_HEAD> 


<TABLE> 
_<TABLE_ATTRIBUTES> 
<TABLE_FILE> 


<TABLE_HEADS> 


Doctype 
ARTICLE 


Global 


MILSPEC 


MILSPEC 

SOFTWARE 
SOFTWARE 
SOFTWARE 


SOFTWARE 


SOFTWARE 
SOFTWARE 
SOFTWARE 
Global 
LETTER 
ARTICLE 


MILSPEC 


OVERHEADS 
SOFTWARE 


SOFTWARE 


Global 
Global 
Global 


Global 


Description 


Provides information pertaining to the original 
source of information for an article. 


Provides access to special characters that are not 
available on the terminal keyboard. 


Creates a listing of information about the 
specification on the title page and creates a 
two line running heading for the rest of the 
document. 


Creates a title with up to seven centered lines on 
the title page. 


Begins a new statement description. 


Begins a section that illustrates the syntax of a 
statement or function including keywords and 
parameters. 


Indicates the position of a valid statement line 
within the context of a statement format or a 
construct list. 


Begins a statement reference section, enables 
tags reserved for use in statement sections, and 
sets paging attributes. 


Begins a new subcommand description. 


Begins a subcommand reference section within 
the command section. Use this section of a 
reference document for subordinate commands. 


. Specifies the heading for text that precedes a 


subcommand section. 
Marks an unnumbered subsidiary heading. 


Specifies the subject of a memo or letter 
and places this information with a heading of 
“Subject:” at the left margin. 


Specifies a subtitle for an article. 


Creates a subtitle with up to seven centered lines 
on the title page. 


Specifies a secondary title line for a new slide. 


Labels a statement that illustrates the syntax of a 
programming language. 


Creates a default heading for the <SYNTAX> 
tag. 


Begins a sequence of columnar data. 
Requests special formatting. 


Causes a separate file containing a formal table to 
be included in the SDML input file. 


Specifies column headings for each column in the 
table. 


D-13 


Summary of VAX DOCUMENT Tags 


Table D—1 (Cont.) Summary of VAX DOCUMENT Tags 


Tag 
<TABLE_KEY> 


<TABLE_KEYREF> 
<TABLE_ROW > 
<TABLE_ROW_BREAK> 


<TABLE_SETUP> 


<TABLE_SPACE> 
<TABLE_UNIT> 


<TABLE_UNIT_HEADS> 
<TAG> 
<TAG_SECTION> 


<TERMINATING_TAG> 
<TEXT_SIZE> 


<TITLE> 
<TITLE> 


<TITLE> 
<TITLE_PAGE> 


<TITLE_SECTION> 
<TOPIC> 
<TO_ADDRESS> 
<U> 


<UNDERLINE> 
<UPDATE_RANGE > 


<UPPERCASE> 


D-14 


Doctype 
Global 
Global 
Global 


Global 


Global 


Global 
Global 


Global 
Global 
SOFTWARE 


SOFTWARE 
OVERHEADS 


ARTICLE 
Global 


OVERHEADS 
Global 


ARTICLE 
OVERHEADS 
LETTER 
Global 


Global 
Global 


Global 


Description 


Begins a key or legend for a table. 


Specifies that a table key should be printed below 
the table (or portion of the table) in which this tag 
appears. 


Specifies text for each column in the current 
table. 


Specifies the boundaries within which a long table 
can be broken onto a new page. 


Declares the number of columns in a table and 
the effective (approximate) width values to be 
assigned to each column. 


Marks the space required for a table that will be 
pasted in during final production. 


Begins a portion of a table containing rows that 
are to be grouped as logical units. 


Specifies headings to be used for a table unit. 
Labels a tag. 


Begins a tag reference section, enables tags 
reserved for use in tag sections, and sets paging 
attributes. 


Specifies the required terminator for a tag. 


Changes the size of type used within the context 
of topics, tables, and lists. 


Specifies the main title line for an article. 


Labels the title used on either a title page or part 
page. 
Specifies a title line for a new slide. 


Labels the beginning of a title page and enables 
the title page tags. 


Begins the title section of an article which spans 
both columns of the article. 


Specifies a line of topic text for a slide. 


Identifies the name and address of the receiver of 
a letter and places this information flush left on 
the left margin. 


Labels the user portion of a dialog between user 
and system in an interactive example. 


Marks a portion of text to be underlined. 


Marks the location at which a new section of 
updated pages begins. 


Labels text that should appear as uppercase in 
the final output. 
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Tag 
<USER_I_MESSAGE> 


<USER—W_MESSAGE> 
<VALID_BREAK> 
<VALID_TABLE_ROW_BREAK> 


<VARIABLE> 
<VBAR> 


<VITA> 
<X> 


<Y> 


Doctype 
Global 


Global 
Global 
Global 


Global 
Global 


ARTICLE 
Global 


Global 


Description . 
Sends an informational message to the terminal 
or log file during processing of a file. 


Sends a warning message to the terminal or log 
file during processing of a file. 


Labels a permissible page break within a 
monospaced example. 


Marks a permissible place that a first-level table 
row may be broken across pages. 


Labels a program variable or number. 


Labels an occurrence of a vertical bar in an 
argument to a tag. 


Provides information about the author's 
professional history. 


Creates an index entry with a reference to the 
page on which this tag appears. 


Creates an index entry with no reference to 
the page on which this tag appears. Used for 
cross-references (“See” or “See also” entries). 
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Index 





A 


<ABSTRACT> 
definition of * 9-2 
<ACCENT> 
definition of * 9-3 
<ALIGN_AFTER> 
definition of © 9-4 
<ALIGN_CHAR> 
definition of ©9—5 to 9-6 
<ALIGN_NUMBER> 
definition of ©9—7 to 9-8 
<AMPERSAND> 
definition of © 9-9 
in math expressions ® 9-142 
Angle bracket in text 
coding an® 2—3 
Appendix 
creating ® 3—5 
<APPENDIX> 
definition of ©9—10 
Arguments to tags ® 2-2 


Backslash 

coding a® 2—5 
<BACKSLASH> 

definition of © 9-11 

in math expressions ® 9-142 
<BAR_CHAR> 

in math expressions ® 9-141 
/BATCH qualifier * A—5 
Bookbuilding * 1-9, 4-9 
Book Elemente 1-9 
BOX tag® 9-12 


C 


<CALLOUT> 
definition of ©9-—13 








<CALLOUTS> 
definition of °9-—15 to 9-16 
<CALLOUT_REF> 
definition of © 9-14 
<CASES> 
in math expressions ® 9-142 
<CDOTS> 
in math expressions ¢ 9-142 
<CENTER_LINE> 
definition of €9—17 to 9-18 
Change Bars 
See <mark> 9-138 
<CHAPTER> 
definition of ©9-—19 
Chapters 
creating ® 3-2 
<CHEAD> 
definition of ©9-—20 
<CHECK_FOR_INCLUSION> 
definition of ©9-—21 to 9-22 
<CHOOSE> 
in math expressions ® 9-142 
<Cco> 
definition of © 9-23 
<CODE_EXAMPLE> 
definition of °9-24, 9-26 
Coding an SDML file * 2-2 
Command line 
introduction to ® 1-4 
<COMMENT> 
definition of °9—27 to 9-28 
<CONDITION> 
definition of ©9—29 to 9-31 
Conditionalized book elements 
building * 4-14 
/CONDITION qualifier ° A—6 
/CONTENTS qualifier ® A-6 
<CONTENTS_FILE> 
definition of © 9-32 
Copyright page 
creating ® 3—4 
<COPYRIGHT_DATE> 
definition of © 9-33 
<COPYRIGHT_PAGE> 
definition of © 9-34 
<CP> 


definition of © 9-35 
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Index 


<CPAREN> 
definition of © 9-36 
Creating © 2—1 
Cross-reference file © 6-2 


D 


<DATE> 
definition of © 9-37 
<DDOTS> 
in math expressions ¢ 9-142 
<DEFINE_BOOK_NAME> ® 9-38 
definition of °9-—38 to 9-39 
<DEFINE_SYMBOL> 
definition of ©9-40 to 9-41 
<DEFINITION_LIST> 
definition of °9-—42 to 9-43 
<DEFINITION_LIST_HEAD> 
definition of © 9-44 
<DEFLIST_DEF> 
definition of © 9-45 
<DEFLIST_ITEM> 
definition of °©9-46 to 9-47 
Destination 
See DOCUMENT command, destination 
parameter 
/DEVICE_CONVERTER qualifier © A—7 
/DIAGNOSTICS qualifier ® A-9 
<DIVIDED_BY> 
in math expressions ® 9—142 
Docset 
VAX DOCUMENT e 1-1 
<DOCTYPE> 
definition of °9—48 to 9-49 
Doctype parameter 
See DOCUMENT command, doctype parameter 
DOCUMENT command 
parameters ® A—2 to A-5 
destination ¢ A—4 
doctype ® A-3 
input-file-spec ¢ A—2 
qualifiers® A-5 to A-16 
/BATCHe A-5 
/CONDITION ¢ A-6 
/CONTENTS ¢ A-6 
/DEVICE_CONVERTER ® A-7 
/DIAGNOSTICS ® A-9 
/ELEMENT ¢ A-9 
/INCLUDE ¢ A-9 
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-_DOCUMENT command 
qualifiers (cont’d.) 


/INDEX ® A-9 

/KEEP*® A-11 
/LIST * A—12 

/LOG*® A-12 

/MAP*® A-13 
/MASTER_INDEX A-13 
/PRINT ® A-13 


/PROFILE e A-15 
/SYMBOLS ¢ A-15 
/TAG_TRANSLATOR ¢ A-15 
/TEXT_FORMATTER #® A-15 
Summary of ® A—1 to A-16 
Syntax of ® A-2 
Document type, specifying to DOCUMENT 
command 
See DOCUMENT command, doctype parameter 
<DOTS> 
in math expressions ® 9-142 
<DOT_CHAR> 
in math expressions ® 9-141 
<DOT_TIMES> 
in math expressions ® 9-142 
<DOUBLE_QUOTE> 
definition of ¢9-50 to 9-51 


E 


Editors 
LSE ¢B-1 
<ELEMENT> 
definition of ¢9-52 
/ELEMENT qualifier ® A—9 
<ELLIPSIS> 
definition of °9-53 to 9-54 
<EMPHASIS> 
definition of ©9-55 to 9-56 
Emphasizing text® 8—1 to 8-3 
<ENDCOPYRIGHT_PAGE> 
definition of °9-57 
<ENDPART_PAGE> 
definition of © 9-58 
<ENDTITLE_PAGE> 
definition of © 9-59 
<EQUALS> 
in math expressions ® 9-142 
Error messages 
syntax of ¢5—1 





<EXAMPLE> 


definition of ©9-60 to 9-61 
Examples 

creating ®*3—19 

formal ¢ 3-20 

informal ¢ 3—19 
<EXAMPLE_ATTRIBUTES> 

definition of °9-62 to 9-64 
<EXAMPLE_FILE> 

definition of © 9-66 
<EXAMPLE_SPACE> 

definition of ©9-67 to 9-68 


F 


<FCMD> 

definition of °9-69 to 9-71 
<FIGURE> 

definition of ©9—71 to 9-78 
Figure attributes 

controlling * 3—16 
Figures 

creating ° 3-14 

margins in® 3—16 

page breaks in® 3-17 
<FIGURE_ATTRIBUTES> 

definition of ©9—79 to 9-80 
<FIGURE _FILE> 

definition of °9-81 to 9-83 
<FIGURE_SPACE> 

definition of °9-84 to 9-85 
File building * 4—2 
<FINAL__CLEANUP> 

definition of °9-86 to 9-87 
<FOOTNOTE> 

definition of °9-—88 to 9-90 
Footnotes 

effect on page breaking in tables * 3—13 
<FOOTNOTE_TEXT> 

definition of ¢9-91 to 9-92 
<FOOTREF> 

definition of °9-93 to 9-94 
<FORMAT> 

definition of 9-95 
<FPARM> 

definition of © 9-96 
<FPARMS> 

definition of * 9-97 
<FRONT_MATTER> 

definition of ©9-98 to 9-99 
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<FUNC> 
in math expressions ® 9-142 


G 


<GDEF> 

definition of *9—100 
Generic Markup Language ® 1-3 
Global tags ® 2-1 
Glossary 

creating ® 3—5 
<GLOSSARY > 

definition of °9—101 to 9-102 
<GLOSSARY TAG> 

begin ® 9-101 
Graphics files 

included in SDML files © 3—18 
<GREF> 

definition of *9—103 
<GROUP> 

in math expressions ® 9-142 
<GTERM> 

definition of °9-—104 


H 


<HAT> 

in math expressions ¢ 9-141 
<HAT_CHAR> 

in math expressions ¢ 9— 141 
Headings 

creating ® 3-2 
<HEADX>” 

definition of ©9-—105 to 9-106 
<HELLIPSIS> 

definition of *9—107 
Hyphen 

coding a® 2-6 
<HYPHENATE> 

definition of *9—108 








<ICON> 
definition of ©9—109 to 9-110 
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Index 


<ICON_FILE> 


definition of ©9—111 to 9-112 
<ICON_TEXT> 
definition of ©9—113 
Illustration of the Workshop Layout Showing 
Forklift® 9-73 
<INCLUDE> 
definition of °9-114 
/\INCLUDE qualifier * A—9 
<INCLUDES_FILE> 
definition of °9—115 to 9-116 
Index . 
creating © 7—2 
in a revision ® 9-188 
/INDEX qualifier A—9 
<INDEX _FILE> 
definition of ©9-—117 
Input file, specifying to DOCUMENT command 
see DOCUMENT command input-file-spec 
parameter 
Input-file-spec parameter 
See DOCUMENT, input-file-spec parameter 
<INTEGRAL> 
in math expressions ¢ 9-142 
<INTERACTIVE> 
definition of ©9—118 to 9-119 


K 


<KEEP> 
definition of °9-—120 
/KEEP qualifier ¢ A—11 
<KEYWORD> 
definition of ©9-121 


L 


Language-Sensitive Editor 

See LSE 
<LBAR> 

in math expressions ¢ 9-142 
<LBRACE> 

in math expressions * 9—142 
<LBRACKET> 

in math expressions ® 9-142 
<LCEIL> 

in math expressions ® 9—142 
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<LE> 

definition of °9-122 
<LFLOOR> 

in math expressions ® 9—142 
<LINE> 

definition of 99-123 to 9-125 
<LINE_ART> 

definition of °9-126 to 9-127 
<LIST> 

definition of °9—128 to 9-134 
/LIST qualifier A—12 
Lists 

creating various types ® 3—5 
<LITERAL> 

definition of *9-—135 
Logical names ® 4—12 
/LOG qualifier ® A-—12 
<LOWERCASE> 

definition of ° 9-136 
<LPAREN> 

in math expressions ® 9-143 
LSE ¢ B-1 
LSE> VAX DOCUMENT tokens and placeholders ® 

B-8 


M 


/MAP qualifier ® A—13 
<MARK> 

definition of °9-—137 to 9-138 
Master index 

creating ® 7—11 
/MASTER_INDEX qualifier © A—13 
<MATH> ® 9-141 

definition of ©9—139 to 9-149 
<MATH_CHAR> ® 9-150 

definition of ©9—150 to 9-158 
<MATRIX> 

in math expressions ® 9-142 
<MCS> 

definition of °9-—159 to 9-162 
Messages ®C—1 to C-—78 
<MINUS> 

in math expressions ® 9-142 
<MOD> 

in math expressions ® 9-142 








N 


<NESTED_TABLE_BREAK> 

definition of ©9-—163 to 9-164 
<NEWTERM> 

definition of ©¢9-—165 
<NOTE> 

definition of *9-—166 


O 


<OPAREN> 
definition of °9—167 
<ORDER_NUMBER> 
definition of ©9—168 
Output device, specifying to DOCUMENT 
command 
See DOCUMENT command, destination 
parameter 
<OVER> 
in math expressions ® 9-143 
<OVERLINE> 
in math expressions ® 9-141 


<P> 

definition of ©9-169 to 9-170 
<PAGE> 

definition of ¢9-171 to 9-172 
Paragraphs 

creating ® 3—1 
Parameters, DOCUMENT command 

See DOCUMENT command, parameters 
<PARENDCHAR> 

definition of ¢9—173 to 9-174 
Parentheses in an argument 

coding ® 2—4 
<PART> 

definition of ©9-175 to 9-176 
<PART_PAGE> 

definition of °9-177 
<PI> 

in math expressions ® 9-143 
<PLUS> 

in math expressions ¢ 9-143 
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<PMOD> 
in math expressions ® 9-143 
Preface © 
creating ® 3—4 
PREFACE tag ® 9-178 
<PREFACE_SECTION> 
definition of *9—179 
Printing 
an existing filee 4—5 
/PRINT qualifier A-13 
<PRINT_DATE> 
definition of °9-180 
Processing ® 4—1 
bookbuilding ¢ 4—9 
element building * 4—13 
steps of ® 1-6, 4-9 
subelement building * 4-14 
Processing individual input files (book elements) ¢ 
4-2 
Profile 
creating ®° 4—10 
example of ¢ 4—10 
preliminary ¢ 6-6 
Processing 
See also Bookbuilding 
valid tags of °4-10 
<PROFILE> 
definition of °9—181 to 9-182 
/PROFILE qualifier A—15 


Q 


Qualifiers 
See DOCUMENT command, qualifiers 
for controlling file processing * 4—3 
-<QUOTE> 
definition of 9-183 to 9-184 


R 








<RBAR> 


in math expressions ® 9—- 143 
<RBRACE> 

in math expressions ® 9-143 
<RBRACKET> 

in math expressions ® 9-143 
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Index 


<RCEIL> 
in math expressions ¢ 9-143 
< REFERENCE > . 
definition of 9-185 to 9-187 
Referencing symbol-names ® 6—4 
Referencing symbol-Names in other files © 6-6 
<REVISION> 
definition of ©9-—188 to 9-189 
<REVISION_INFO> 
definition of ©9—190 
<RFLOOR> 
in math expressions ® 9-143 
<RIGHT_LINE> 
definition of °9-191 
<RPAREN> 
in math expressions ® 9—143 
<RULE> 


definition of °9—192 


S 


<S§> 

definition of ©9—193 to 9-194 
<SAMPLE_TEXT> 

definition of °9-195 
SDML file, specifying to DOCUMENT command 

see DOCUMENT command input-file-spec 

parameter 

SDML input files 

creating ® 2-6 
<SET_CONDITION> 

definition of ©9—200 
<SINGLE_QUOTE> 

definition of ©9—201 to 9-202 
<SP> 

in math expressions ® 9—143 
<SPAN> 

definition of ©9—203 to 9-204 
Special features ®* 8-1 to 8-9 
<SPECIAL_CHAR> 

definition of ©9—205 to 9-206 
<SQRT> 

in math expressions ® 9—143 
<SUBHEADx> 

definition of ©°9—207 
<SUBSCRIPT > i 

in math expressions ® 9-143 
<SUM> 

in math expressions ® 9-143 
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Summary of Alternate Designs for Doctypes ® 
9-48 

<SUPERSCRIPT > 

in math expressions ® 9-143 
Supported Document Types ® 9-48 
Symbol definitions file © 6-6 
Symbol-names 

controlling the output of references to 

See also <REFERENCE> ® 6—4 

Referencing ® 6—4 

rules for creating * 6—1 
Symbol-names for text and book elements ® 6—2 
/SYMBOLS qualifier ®° A—15 
Syntax 

See DOCUMENT command, syntax of 


T 


<TABLE> 

definition of ¢9—208 to 9-209 
Table attributes 

controlling ® 3—10 
Table of Contents 

creating ® 7-1 

in a revision ® 9—188 
Tables 

creating ® 3-6 

margins in® 3-10 

page breaks in® 3—12 
<TABLE_ATTRIBUTES> 

definition of ©9-—210 to 9-211 
<TABLE_FILE> 

definition of ©9-—212 to 9-213 
<TABLE_HEADS> 

definition of © 9-214 
<TABLE_KEY > 

definition of ©9—215 to 9-216 
<TABLE_KEYREF> : 

definition of °9-217 
<TABLE_ROW> 

definition of 9-218 to 9-219 
<TABLE_ROW_BREAK> 

definition of ©9—220 to 9-222 
<TABLE_SETUP> 

definition of ©9-—223 to 9-224 
<TABLE_SPACE> ® 9-225 

definition of °9-—225 to 9-226 
<TABLE_UNIT > 


definition of ¢9-—227 to 9-228 





<TABLE_UNIT_HEADS > 
definition of ©9—229 to 9-230 
<TAG> 
definition of © 9-231 
Tags 
context-sensitive ® 1-9 
doctype-independent® 1—8 
doctype-specific * 1-8 
summary of ©D-—1 to D-—15 
Tags for Mathematical Functions ® 9-144 
/TAG_TRANSLATOR qualifier ® A—15 
<TEXT> 
in math expressions ® 9-143 
Text elements ® 2—1 
/TEXT_FORMATTER qualifier A—15 
<TILDE> 
in math expressions ® 9-141 
<TILDE_CHAR> 
in math expressions ® 9-141 
<TIMES> 
in math expressions ¢ 9-143 
<TITLE> 
definition of © 9-232 
Title page 
creating ® 3-3 
<TITLE_PAGE> 
definition of © 9-233 
<TO> 
in math expressions ® 9-143 
Troubleshooting output problems ® 5-3 
missing spaces in code examples ® 5—3 
paragraph indentation ® 5-3 
problems with examples ¢ 5—3 
sequencing of formal. elements ¢ 5—4 


U 


<U> 

definition of ¢9—234 to 9-235 
<UNDERLINE> 

definition of © 9-236 

in math expressions ¢ 9-141 
<UPDATE_RANGE> 

definition of ©9-—237 to 9-239 
<UPPERCASE> 

definition of °9-240 
<USER_I_MESSAGE> 

definition of ©9-241 to 9-242 
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<USER_W_MESSAGE> 


definition of ©9-243 to 9-244 
Using Basic Text Elements ® 3-1 to 3-21 


V 


<VALID_BREAK> 

definition of °9—245 to 9-247 
<VALID_TABLE_ROW_ BREAK > 

definition of * 9-248 
<VARIABLE> 

definition of °9-—249 

in math expressions ® 9-143 
VAX DOCUMENT 

See DOCUMENT command 
<VBAR> 

definition of *9—250 
<VDOTS> 

in math expressions ® 9-143 
<VECTOR> 

in math expressions ® 9-141, 9-143 
Vertical bar or ampersand 

coding a® 2—5 


X 


<X> 
definition of ©9-—251 to 9-253 
<X_TIMES> 
in math expressions ® 9-143 
XREF file © 6-2 
<xs> tag 
See <x> tag 
See <y> tag 
<XSUBENTRY> tag 
See <x> tag 
See <y> tag 
<x> tag® 7-2 


Y 


<Y¥> 
definition of °9—254 to 9-255 
<y> tag® 7-2 
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